Most issues come down to a document waiting in a pipeline step, a missing index, or credits. Start here.
Processing#
My document stays in the same status#
- Background tasks run on schedules, so give it a few minutes and click the refresh icon on the Documents grid.
- Check that you have credits left (Dashboard). AI steps stop when the balance is exhausted and auto charge is off.
- Platform administrators: open Platform management → System Tasks and check that the task for that status is active and scheduled, then look at the Hangfire Dashboard for failed runs. Run now processes the next batch immediately.
| Stuck in | Task responsible |
|---|---|
| Waiting for pre processing | Split documents |
| Waiting for versioning | Detect document versions |
| Waiting for OCR start / OCR completed | Convert documents to text / Index documents |
| Indexed | Map JSON (needs a document type with a template and an index) |
A document is Permanently failed#
OCR or splitting failed three times. Common causes are damaged or password-protected files, or an external service being down at the time. Administrators can find the reason under Platform logs → AI job failures or OCR service logs. Fix the cause and upload the file again.
The document never becomes Searchable#
- Does it have a Type? If not, set one from the context menu.
- Does that type have a saved JSON template?
- Has the type's index been created? Check with Index status on the Search page.
See Search indexes.
The wrong document type was detected#
Correct it with Document type in the context menu. To prevent it, deactivate types you don't use and give similar types clearly different names.
Extracted values are missing or wrong#
- Check the Text tab first: if the text is wrong, the scan quality is the problem, not the schema.
- Improve the template (clearer field names, correct types) and use Recreate JSON on a sample.
- When the template is right, run Re-index documents for the type.
Uploading#
My file was not uploaded#
- Not supported: the extension is not an active content type; see Supported file types.
- Duplicate: an identical file already exists and
DefaultDuplicateBehaviouris Do not upload. Hover the status to see which document it duplicates. - Too large: browser uploads are limited to 200 MB.
Emailed attachments don't appear#
- Make sure the email was sent to your exact capture address (Initial Setup) and has real file attachments, not links or inline images only.
- Mail is picked up on a schedule; wait for the next Capture mail run.
- Administrators can check Error Logs for MailCapture entries.
A new upload didn't become a new version#
Versioning matches on the exact file name and extension and needs UseVersioning = Y. Files registered through
/api/documents/record are not versioned.
Search#
AI search returns nothing#
- Check Index status for the selected type: are there Searchable documents?
- Look at the generated query: does it use the fields and values you expected? Adjust it in the query builder and use Run query.
- Rephrase using field names from Index fields.
Keyword search misses a recent document#
The document must reach Indexed first. Check its status on the Documents page.
Access and API#
A page is missing from my menu#
Pages are granted to roles. Ask your organization manager to grant the menu item to one of your roles or to add a user exception; see How permissions work.
The API returns 401#
Send both X-Api-Key and X-Api-Secret, copied exactly from Initial Setup, and make sure your client
doesn't drop custom headers on redirects (always call the HTTPS address).
The API returns 409#
A documentId you sent to a record endpoint already exists. Record ids must be unique, so prefix them with your
source (for example portal-); the response lists the ids that clashed.
The API returns 404 for a document I just uploaded#
Use the documentId from the upload response, not the file name — POST /api/documents generates the
id. Ids are also per organization, so a key from another organization will not find it.
How do I know when a document is ready?#
Poll GET /api/documents/{id}/status and wait for
isOcrCompleted. Don't poll faster than every few seconds: OCR of a large PDF takes minutes.
Still stuck?#
Note the document name, the time, and what you expected, and contact your platform administrator. Administrators can correlate it with the Activity, Error, AI and OCR logs described in Platform operations.