Overview
When an AI agent can't read a document, the record fails with a message on the flow step's Errors page, in the run console, and in the agent's preview. When the agent reads the document but returns incomplete or incorrect data, there's no error, and the fix is usually in the instructions, the schema, the model, or the document itself. This article covers both: the error messages you can see, what causes each one, and how to improve extraction quality.
Before you start, confirm that intelligent document processing is turned on for your account. With the setting off, the model reads each file on its own, and many file types fail. See Turn on intelligent document processing.
Error messages
| Message | Cause | What to do |
|---|---|---|
| This file type is not supported. Supported types include images, PDF, DOC, DOCX, PPT, PPTX, XLS, XLSX. | The file's type isn't supported, or its name has no extension and Celigo couldn't identify it from its contents. | Save the file in a supported format, or map the file name with its extension. See Supported file types and limits for intelligent document processing. |
| This file exceeds the maximum supported size of 20 MB. Please upload a smaller file. | The file is larger than 20 MB. | Split the file, reduce scan resolution, or compress embedded images, and retry. |
| Each file must include a blobKey. Please fix the file list and try again. | The agent's files mapping has an entry without a file reference. | Map the file reference (blobKey) from the step that brings in the document. |
| This model cannot read this file type. Please use a PDF, or convert the file to a supported format. | Intelligent document processing is turned off, and the model can't read this file type. | Turn on intelligent document processing, or convert the file to PDF. |
An error from Gemini that mentions a mimeType parameter that isn't supported |
Same as the previous row, reported in the provider's own words. | Turn on intelligent document processing, or convert the file to PDF. |
| Document is encrypted or password-protected. | The file has a password or is encrypted. | Remove the password, and retry. |
| Document parsing timed out. | The document took too long to process, which is most common with long scanned files. | Split the file into smaller files, and retry. |
| We could not extract content from this document. Please try another file or try again., or a similar message that the document couldn't be parsed or no content was extracted | The file is empty, corrupted, a blank or unreadable scan, or a format variant Celigo can't read. | Retry once. If it fails again, open the file to confirm it has content, re-save it in a supported format, or try another copy. For a clearer scan, rescan at a higher resolution. |
| Document parsing is not configured. Please contact your administrator. | Document processing isn't available to your account. | Contact Celigo Support. |
| insufficient AI agent prepaid credits | Your account's AI credits balance is zero. | Request more AI credits. See Track your AI agent actions and credits usage. |
| A message that the response doesn't match the output schema | The agent's response didn't conform to the JSON schema, so no data was passed downstream. | Check the schema for fields that should allow null, types that are too strict, or a structure the model can't produce, and test in the agent's preview. |
Extraction quality issues
These problems don't produce an error. Preview the agent with the same document to see exactly what it returns, and change one thing at a time.
| Symptom | Likely cause | What to do |
|---|---|---|
A value comes back null
|
The value isn't in the document, the label is unusual, or a scan is hard to read. | Confirm the value is on the page. Add the labels the document uses to the field's description, such as "also printed as Remit-to or Pay to." For scans, rescan at a higher resolution. |
| The agent picks the wrong value | The document has several candidates, such as a subtotal and a total. | Say in the instructions exactly which one to use and which to ignore. |
| Dates, amounts, or codes come back in different formats | The instructions or schema don't specify a format. | State the format in the instructions and in each field's description, such as YYYY-MM-DD for dates and ISO 4217 codes for currencies. |
| Line items are missing | The table continues past page 50, or rows were read as headers or subtotals. | PDFs are read up to page 50; split longer files. Tell the agent which rows are line items and which to skip. |
| Repeated header or subtotal rows appear as line items | The instructions don't tell the agent to skip them. | Add "Don't return repeated header rows, subtotal rows, or tax rows as line items." |
| A photographed or scanned page saved as PNG or JPEG is read poorly | Images are read by the model's own vision, not Celigo's optical character recognition (OCR). | Save scans as PDF or TIFF so Celigo's OCR reads them, or try a more capable model. |
| The agent reads the wrong sheet of a workbook | Every sheet is read. | Name the sheet to use in the instructions. |
| The agent returns data for only one of several documents in a file | The schema returns a single document. | Return an array of documents, and use one-to-many on the next step. See Extract data from documents. |
| Extraction is accurate on some layouts but not others | The instructions describe one layout. | Test each layout in preview, and describe the differences in the instructions. For several document types, classify first and use a separate extraction agent per type. |
| Results vary between runs of the same document | The model's settings allow variation. | Set Temperature to 0 in the model's advanced settings, if the model offers it. |
| Scanned documents in other languages are extracted poorly | OCR recognizes languages written in the Latin alphabet only. Scanned pages in other scripts, such as Chinese, Japanese, Korean, Arabic, or Russian, aren't recognized. Digital text with selectable characters is read in any language. | Ask the sender for a digital document with selectable text, or try a more capable model on an image of the page. |
| Handwritten values are missing or wrong | Handwriting isn't supported. | Ask the sender for a typed or digital document. |
AI credit usage is higher than expected
Long documents use more credits because the extracted content is input to the model. To reduce usage:
- Send only the files the agent needs, and split long files so the agent reads only the relevant pages.
- Classify documents with a smaller model first, and send only the matching type to the extraction agent.
- Compare a smaller model on your samples in preview; well-structured documents often don't need the most capable model.
The preview shows the AI credits used by each test, and execution logs show usage for each run. See Monitor AI agent and guardrail activity with execution logs.