Troubleshooting: Common Errors and Fixes

The in-app Troubleshooting & FAQ doc is the quick version; this page is the full symptom → cause → fix map, extended with the login, MFA, and run-lifecycle cases the in-app doc does not cover. Read the row, do the check, apply the fix. When the fix does not land, escalate to support.

Where errors are visible

Before the table: know where each kind of error shows up.

• The study’s step stepper — the pipeline’s own progress (Queued through Final Analysis). A stuck or failed run is readable here first.
• The job log — the async job behind a run: its state and its error.
• The audit trail — every state transition with timestamps and actors, so “who did what and when” is answerable from the record, not from memory.
• Access & security logs — failed logins, MFA failures, exports, and views; the evidence view for anything that smells like an access problem.

The symptom table

Symptom	Likely cause	Check first	Fix, or who to contact
File rejected on upload (“File too large”)	The file exceeds the 50 MB per-file limit	The size of the file you are sending	Split the data across multiple studies or drop unused columns; re-upload
Upload rejected on the file type	Only Excel workbooks are accepted (.xls, .xlsx, .xlsm); CSVs are refused at the door on purpose	The extension	Re-save the dump as an Excel workbook and upload again
“Could not detect required columns: …”	The header names do not resolve to the platform’s line-item vocabulary	The header row detected in the mapping preview	Rename the headers to common terms (Revenue, Operating Profit, Cost, entity name) or complete the manual mapping; the preview lists exactly which required columns are still missing
The run will not start on the selected PLI	The dump does not carry the columns that PLI is computed from (a Berry Ratio needs gross profit and operating expenses; EBITDA/Sales needs EBITDA)	The required-column list shown for the selected profit-level indicator	Either add the missing lines to the dump, or select a PLI the dump can support — the default operating margin on cost needs only Operating Profit and Cost
Wrong sheet in the analysis	Multi-sheet workbook; the dump sheet was not the one read	The sheet selected in the wizard	Re-open the wizard and select the dump sheet, then re-run
Study stuck in Processing	A pipeline step is in flight, or the worker is queued behind other runs	The current step in the stepper; the job log	The eight steps are Queued → Final Analysis; a normal run takes minutes. Automatic retries cover transient upstream failures; if the step has not advanced, re-submit the run — that is the workflow’s own path
Job failed (study in Failed state)	A run error: data shape, an AI step failure, an upstream outage	The error recorded on the study and its job	Re-submit the run (Failed → Processing is a supported transition); if it fails twice on the same step, contact support with the study name
AI screening fails for every company with a model/provider error	The deployment’s model slugs and its gateway host disagree, so each call is rejected — the mismatch is flagged as a configuration warning at startup	Nothing you can fix from the workspace	Contact support: this is deployment configuration, not your data
No comparables remain after screening	Over-strict quantitative filters	The revenue band, the related-party percentage cap, and the revenue unit you declared (actual / thousands / crores)	Widen the band, relax the cap, or correct the unit — a unit declared one scale off makes every filter look like a rejection
Comparables you expected to keep were dropped as outliers	Extreme margins are a documented non-comparable reason (possible hidden IP or non-routine functions), and the statistics engine trims beyond the interquartile range before computing	The screening reason recorded on each dropped company, and the resulting sample size	Where the exclusion is wrong for your facts, override the disposition with a documented reason — the override is logged and the range is recomputed
The range looks wrong (a unit or sign problem)	Mixed reporting units across years, a signed operating loss, or a mis-mapped column	The column mapping and the multi-year averaging setting	Correct the mapping or the averaging, then re-run; excluding the one odd company is the last resort, not the first
Report or workbook rebuild fails with DUMP_EXPIRED	The working dump parquet has passed your tenant’s retention window (default 7 days, configurable 1–31, timed from when the study entered review)	How long ago the study entered review	The settled study record still governs the workflow; regenerate from the current run, or ask support to restore the working data if it is still within the window
Study is read-only when you expect to edit it	The study’s state governs what it accepts; review, sign-off and archive are past the editing stage	The study’s state	Work in the states that accept the edit; an archived study is immutable by design — open a new study
Cannot approve or sign off	The study is not in the state your role acts on, or the role is wrong	The study’s state and your role	Confirm the state and the role; the Firm Admin can check the assignment
403 / Access denied on an action	The role does not allow that action, or the plan does not hold the feature	Your role against the action; whether the capability appears in your sidebar at all	Ask your Firm Admin. A capability you cannot see is usually the plan boundary, not a fault: gated features are hidden, and the backend denies them regardless
Too many requests / 429 on login	The auth endpoints are rate-limited, and the MFA code step is the tightest	How many attempts you have just made	Stop and wait for the window to clear; use the reset flow rather than retrying the password
Login blocked: captcha verification failed	The Turnstile widget did not render or the token went stale (where the deployment enables it)	Whether the widget rendered before you submitted	Reload so the widget renders, then submit again. Where enabled it fails closed — there is no silent fallback
MFA code rejected at login	A wrong code, clock drift, or a lost device	The authenticator app; a backup recovery code	Redeem a single-use backup recovery code (ten are issued at enrolment). If the device and the codes are both lost, see below
Login blocked: terms consent required	The deployed terms version changed and your stored consent is stale	The re-consent view at login	Read the linked terms and privacy policy and accept; login completes after re-consent
Session expired / signed out	The access token is short-lived (30 minutes by default) and is rotated on refresh	—	Sign in again. A password reset, a role change or an admin revocation bumps the user’s token version and kills every outstanding session at once — by design
Download link expired	Presigned download URLs are short-lived (300 seconds by default)	—	Request a fresh link from the report workspace; every download is logged
Feedback form returns “Feedback is not configured yet”	The deployment has no feedback webhook URL set	Nothing to change in the form	Use the support channel on the Support tab instead, and tell the Firm Admin so the deployment can be configured
Report shows stale numbers	The export ran before the latest approved benchmark	The job state at export time	Re-run the export after the study’s processing has settled

The two hardest cases

A study stuck in Processing. The run is an async pipeline, and the stepper is the source of truth: if a step is highlighted and advancing, wait. If the state has not moved at all for a long time, the job is the object to inspect — its log carries the error. The recovery path is the workflow’s own: re-submit the run. Do not delete and recreate the study as a first resort; a re-run preserves the record, and a recreated study orphans the audit trail.

An MFA lockout. A user who has lost their authenticator device cannot bypass the code step — there is no client-side bypass, by design. The single-use backup recovery codes are the first fallback; the login flow has a recovery-code path for exactly this. When the codes are gone too, the only path is the platform superadmin’s MFA recovery: the secret is cleared, the password is rotated, and the user re-enrols at the next login. The Firm Admin raises this through support; the new password is communicated out-of-band.

When to escalate to support

Escalate rather than retry when:

• the fix in the table has been applied and the symptom persists;
• the same run fails twice on the same step;
• the error touches data of another firm, billing, or the platform itself;
• an access problem does not resolve by checking the role;
• an MFA lockout has no remaining recovery code.

Contact support carries the standard channel and, for firms whose plan holds priority_support, the priority routes shown on the card. The response-time wording on those cards is display config, not a service level — the times you are owed are the ones in your engagement agreement.

Write a report that moves things

A complete report gets fixed faster. Include:

1. What you were doing (the screen or the step).
2. What you expected to happen.
3. What actually happened (the exact error text).
4. A screenshot, or at least the study name.
5. Your role and your browser.