Troubleshooting

This chapter explains what to do when a document doesn't process cleanly: where to look, what the common validation messages mean in plain language, what a duplicate flag means, what the "awaiting credits" and "awaiting verification" states mean, and how to reach support when you're stuck.

The pipeline errors page

Settings → Logs & tools → Pipeline errors (Admin role) lists the most recent extraction and ingestion failures for your workspace — the last 200, newest first. Each row shows:

• When the error happened.
• Stage — which part of the pipeline failed (classify, parse, or extract).
• Type — exception (something broke) or validation (the document processed but failed a cross-field check).
• Document — the source filename.
• Error — the error message, plus a count of any validation errors on that attempt.
• A View → link straight to the document.

This is the fastest way to see whether a batch of failures shares a common cause (the same vendor, the same file type, the same validation rule) before you contact support.

Common validation failures, in plain language

After extraction, DocReadi runs a set of cross-field checks. Any failure sends the document to the review queue regardless of how confident the model was — see How processing works for the full confidence-gate picture, and Reviewing documents for how to fix a flagged document. Where a warning comes from a check you can configure, Admins and above see an Adjust this check in Settings → Features link directly under it, taking you straight to that check's row — a handful of checks (subtotal + VAT vs. total, the amount-payable math, due date before invoice date, currency validity, and the check that the party, document number and total can be found in the document's text) have no such link and no "off" setting in your workspace: a document that fails one of those is misread, not merely flagged differently, so a workspace can't switch them off. The checks you'll see most often:

• "line_items_sum (X) != subtotal (Y)" — the line items on the document don't add up to the subtotal it states. Usually means a line was missed or duplicated during extraction (common on long, multi-page invoices), or the document itself uses an unusual line-item layout. Check the line items against the source document and correct them, or use Re-extract. If the document view shows the amber "line items look like credits" warning, a credit line lost its minus sign — check it and use Apply credit signs (see Credit lines that lost their minus sign). The check stays silent when no line carries an amount of its own, because there is nothing to add up.
• "Some item rows weren't extracted" — the document prints N item rows but fewer were extracted. A row may have been dropped (often one with no amount of its own, such as a component listed under a bundle heading) or merged into the row above it. Compare the lines with the document's item table, then use Edit Fields or Re-extract. If you add or delete a line in Edit Fields, the check stops for that document: the lines are then yours, so deleting a row on purpose clears it. DocReadi only raises this when it can count the rows reliably, so it stays silent if the document has no item table, several item tables, or a scan whose table was flattened. You can switch it off in Settings → Features (Check every printed item row was extracted).
• "subtotal + vat_amount != total_amount" — the subtotal and VAT amount on the document don't add up to the stated total. Check whether the document has a discount, a freight, service-charge, or surcharge line (Charges), or a VAT-inclusive presentation that wasn't read correctly.
• "amount_payable (X) != total_amount + gratuity_amount (Y)" (with - prepaid_amount and + rounding_amount added to the right-hand side when the document has those, too) — only raised when the document has a gratuity/tip, a deposit already paid, or a cash-rounding line — the amount actually payable doesn't match the total once those are applied. Check the Gratuity / Tip, Deposit Already Paid, and Rounding fields against the source.
• "unusual VAT rate: X%" — the effective VAT rate on the document falls outside the plausible range for your workspace's configured tax jurisdiction (see Workspace administration for setting the tax country). If you regularly deal with zero-rated or non-standard VAT, this may be expected — a reviewer can approve it anyway, confirming the check when asked.
• "due_date is before invoice_date" — the due date on the document is earlier than its invoice date. Usually a misread date (day/month swapped, or the wrong field picked up).
• "payment terms exceed 180 days — unusual" — the gap between invoice date and due date is unusually long. Expected for some long-term supply or service contracts; otherwise usually a misread date.
• "multiple invoice numbers found in document" or "multiple invoices found in document" — the parsed text shows signs of more than one invoice, which usually means the upload is actually several documents in one PDF. The first wording appears when a second invoice number is printed (it names the extracted number and the others it found). The second appears when no second number is found but the file shows two or more different invoice dates plus one other sign: the invoice heading (such as "TAX INVOICE") starting again after a total, or a second grand total. Headings and totals alone do not trigger it, and a bracketed or negative total on an invoice is treated as an adjustment, not a second invoice. Numbers and dates are also read from a column-header table ("Invoice Number" and "Invoice Date" over a single row of values). Two invoices dated the same day are found only by their numbers. The detail lists what was found. If it adds that the extracted number and total "come from different invoices in this file", the record mixes two invoices and its fields need checking. On a credit note, invoice numbers are read as references to the invoice being credited and are not counted. The detail ends "Split it in the split editor at /ui/documents/<id>/split", and the warning card has an Open the split editor button, so you can separate them — see Sending documents in and Reviewing documents.
• "period_end is before period_start" — the document-level billing period's end date is earlier than its start date. Usually the two dates are swapped, or an ambiguous date format was read the wrong way round. Check the period printed on the document, then correct it under Edit Fields.
• "billing period dates are not valid ISO dates" — one of the document-level period dates couldn't be read as a date at all. Correct it under Edit Fields.
• "payee differs from the document issuer" — the document names a different party to pay than the one that issued it. This is legitimate for factoring or group treasury arrangements, but a changed remit-to party is also a common sign of invoice fraud — before paying, confirm the payee with the supplier on a phone number you already hold for them. See Editing fields for where the Payee field lives.
• "currency '¥' is ambiguous …" — the document shows ¥, which is the symbol for both the Japanese yen and the Chinese yuan. DocReadi picks one only when the seller's own country is clear from the document (the seller's address, country or VAT number — never the buyer's), or when only one of the two is ticked under Currencies you work in; otherwise it leaves the currency empty rather than guess. Set JPY or CNY under Edit Fields. RMB and CN¥ always mean the Chinese yuan, and 円 and JP¥ the Japanese yen, so they never raise this warning.
• "currency '…' is not enabled for this workspace" (shown as Currency isn't one your workspace works in) — the document's currency is one your workspace has unticked under Currencies you work in. DocReadi doesn't switch it to a currency you have ticked; it keeps what the document shows — or, for a shared symbol such as $, the currency the seller's country uses — and asks you to check. When the message adds "here it reads as …", the seller's country points to more than one currency and all of them are switched off. Correct the currency under Edit Fields if it was misread, or tick the currency in Settings if you do work in it, then click Re-validate.
• "currency 'pounds' was read as GBP, but the seller's country (…) does not use that name" — "pound" and "£" are read as British pounds, and "lira" as Turkish lira, unless the seller is in a country that uses the same name for its own currency (an Egyptian seller's pounds are Egyptian pounds, a Lebanese seller's lira are Lebanese pounds). "Yen" works the same way, and "yuan" and 元 read as the Chinese yuan unless the seller is in a place that uses the name for its own currency (Taiwan, and for 元 also Hong Kong and Macau). When the seller is somewhere that uses neither, DocReadi keeps the usual reading and asks you to check it. A three-letter code printed on the document, such as GBP, is always used as printed.
• "… date not printed on the document" (shown as Date not on the document) — the extraction returned a date (an invoice or receipt date, say) that appears nowhere in the document's text, so DocReadi cleared it rather than store a date the document never printed. The warning names the date that was removed. If the document does show a date (handwritten, or in a stamp the text reading missed), enter it under Edit Fields; if it shows none, save the field empty and the warning clears. This is one of the checks a workspace can't switch off.
• "iban: is not a valid IBAN", "vendor_vat_number: is not a valid … VAT number" and similar — an IBAN, VAT number, BIC, bank routing code or registration number fails its check digits or doesn't have its expected format. Usually one character was misread (0 for O, 1 for I); sometimes the number on the document itself is wrong. Compare it with the document character by character and correct it in Edit Fields. The message never repeats the number. A number DocReadi can't place — no country prefix and no country on the document, a different kind of number in that field, or extra words written next to it — is left alone rather than flagged. A South African VAT number you have already saved on a confirmed counterparty or one of your entities is not flagged by the check-digit rule, because that rule is our own rather than a published SARS one. These checks are on by default and can be switched off under Settings → Features.

Statement checks

A vendor or customer statement is checked against its own ledger rather than against invoice arithmetic — it carries no line items, subtotal or tax total to reconcile (see Statements of account). These checks run automatically on every statement, as soon as it is processed:

• "statement does not balance: opening X + movements Y = Z, but closing balance is C" — the movements between the opening and closing balance don't add up to the closing balance the statement prints. Usually a row was missed, read twice, or read with the wrong sign. Try Re-validate first: as well as re-deriving the row signs, DocReadi takes the opening and closing balance from the ledger's own opening and closing row whenever the figure at the top of the statement disagrees with it — which clears this flag on a statement that prints no header balance at all. It only does that when a single row states that position; if two rows claim to be the opening, it leaves the figure alone and the flag stands.
• "row N ... running balance R does not follow from P + A" — a single row breaks the running balance printed beside it. Try Re-validate first: DocReadi re-derives the row's Amount from the printed running balances before checking again, and that alone clears most of these, with no re-extraction. If the flag doesn't clear, the running balance itself was most likely misread — DocReadi always takes it as printed, so the message still names the exact row to check against the source; correct the row's Debit, Credit, or Balance figure in the Transactions editor under Edit Fields (see Reviewing a statement) and save — the Amount re-derives itself from what you enter.
• "row N ... has both a debit and a credit" — one ledger row was read as carrying an amount in both columns, which a statement row shouldn't. Usually two rows read as one; if it's just a misread, clear the wrong column in the Transactions editor and save.
• "aging buckets sum to X but the statement total is Y" — the aged-balance buckets printed at the foot of the statement don't add up to its total.
• "N invoice row(s) carry no document_number" — some rows were read as invoices but no invoice number was captured for them, so those rows don't say which invoice they refer to.

For the running-balance row check, try Re-validate before anything else — see Reviewing a statement. For the others, reprocessing the statement is usually the right response: these are reading errors on a ledger, not fields you can correct one at a time.

Rolling-account bill checks

Municipal, utility and telco bills print a running account balance beside the period's charges. The figure DocReadi books is always this period's charges, never the account balance — even when the account is in credit and the closing balance is negative. These checks confirm that, and they only run on a document that actually prints both a previous balance and a closing balance, so an ordinary invoice can't trip them:

• "The account balance was booked instead of this month's charges" — the total came back as the closing account balance rather than what this bill charges. Set the total to this period's charges including VAT via Edit fields; the account balance stays recorded in its own fields.
• "Current charges don't match the invoice total" — the bill states this period's charges as one figure and the booked total is another. On a rolling-account bill they are the same number, so one of the two was misread.
• "The account number was the supplier's bank account" — the number read as your account with this supplier was identical to the supplier's bank account number (or the account part of its IBAN), so it was cleared. Open Edit Fields and enter your account number under Your account with this supplier if the document prints one, then save. Saving clears the note either way.
• "The account summary doesn't add up" — the previous balance, the payments received and this period's charges don't reach the closing balance the bill prints. Usually one of those figures was misread, or a payment row was missed. Check the account summary block on the bill and correct the figures via Edit Fields.

These checks are controlled by Check rolling-account bills reconcile on your Features page, which is on by default. The account fields themselves are described under Rolling-account bills.

If a validation message doesn't match anything above, the document viewer's error detail and the pipeline errors page both show the exact message — include it when you contact support.

An e-invoice XML DocReadi couldn't read

An .xml file is accepted only if it's one of the e-invoice formats DocReadi reads — UBL 2.1 or UN/CEFACT CII (see E-invoice XML). When it isn't, the document is marked Failed and the reason appears on the pipeline errors page:

• "Not a recognised e-invoice XML…" — the file is XML, but not a UBL 2.1 Invoice or CreditNote and not a CII CrossIndustryInvoice. A FatturaPA file, an export in a supplier's own XML dialect, and a file that isn't valid XML at all all land here. Ask the sender for a PDF, or for one of the supported formats.
• "XML e-invoice could not be mapped…" — the format is right, but the file carries neither a document number nor a party name, so there was nothing to record. Usually a truncated or half-written file; ask for it again.

Neither case falls back to a model: an e-invoice XML is read from the file or not at all. Re-sending a corrected file is the fix.

Separately, if you pick one of your custom templates when sending an XML file, the document stops at Failed without an entry on the errors page. Send it again with no template selected — e-invoice XML maps onto the built-in invoice types.

Duplicate documents

DocReadi checks new documents against your workspace's recent history for likely duplicates — the same PDF re-uploaded, the same vendor and invoice number, or a very similar amount and date. When a likely duplicate is found, it's flagged on the document in the review queue rather than silently dropped, so a reviewer decides: reject it as a duplicate, mark it Not a duplicate, or Keep this one (it becomes the original and the other document is flagged instead). See Resolving a duplicate for how each works.

A document stuck mid-processing

Most documents move through the pipeline in seconds. If one is stranded mid-flight — for example because DocReadi restarted for a deploy — the system notices on its own and retries it automatically, with no action needed from you. A document that keeps failing doesn't retry forever: DocReadi retries it automatically up to three times, and if it still hasn't completed, it stops retrying and the document is marked Failed, with a message in the error log explaining what happened ("Processing was retried automatically 3 times without completing…") — see the pipeline errors page for where that message shows up.

If the document-reading (OCR) service is rate limiting — for example after you reprocess or upload many scans at once — the document is not marked Failed. It goes back into the queue and is retried automatically after about 30 minutes, up to 10 times. These waits don't count towards the three retries above. Its error log shows a rate_limited entry: "The document-reading service is rate limiting us (too many documents at once). This document is back in the queue and will be retried automatically — no action needed." Only if it is still rate limited after the automatic retries does it read Failed, with the message "The document-reading service was still rate limiting us after 10 automatic retries, so we stopped retrying. Press Resume to try again."

If a re-run (Reprocess) fails, the document viewer says "This re-run didn't finish, but the previous extraction is kept. You can restore it." and offers Restore previous. This appears only when there was an earlier extraction to go back to, not on a first-time extraction.

If a document still sits at Ingested, Classified, or Parsed for more than a few minutes, or sits at Failed, the dashboard shows a Resume N stuck documents button. Clicking it re-dispatches every stuck document through the pipeline again with a fresh set of automatic retries — safe to use any time, since it only touches documents that have genuinely stalled (not ones still actively processing).

A document parked at awaiting credits or awaiting verification is never counted or reset by this button — being parked isn't being stuck, and one that already finished its extraction is done work waiting for a restore, not stalled work waiting for a re-run. Pressing Resume never throws away a parked document's extraction. Instead, parked documents are handed to their own resume: one that already has an extraction is restored in place, and one that doesn't is queued to run. The banner that follows reports what actually happened, not just what was attempted: if nothing could move yet, it says those documents are waiting on credits or email verification and were left untouched with their extractions intact; if everything released, it reports how many of the total were released; and if only some did — for example a workspace with credits again but an email still unverified — it reports the same release count plus how many are still waiting on credits or email verification.

If you click an action on the documents list — Approve, Reject, or similar — at the exact moment DocReadi is restarting for a deploy, you may briefly see "DocReadi was just updated — refreshing this page…" instead of a raw error. The page reloads on its own a couple of seconds later; no action is needed, and nothing you did was lost. Any other action error still shows its own explanation, and that one you should read and act on as usual.

The "awaiting credits" state

A document shows status awaiting credits when your workspace ran out of credits partway through processing it. The document isn't lost and nothing extracted so far is discarded — it's simply parked, and the Resume N stuck documents button leaves it alone rather than resetting it. As soon as your workspace is topped up (or your plan renews), documents parked at this status resume automatically; you don't need to retry them by hand. See Billing and credits for how to check your balance and top up.

In rare cases, a document parked here already carries a finished extraction that's still waiting on a billing check behind the scenes. If you use Restore previous on one of these before that check clears, it may refuse with a message saying the document is still waiting on a billing check and can't be restored yet. Nothing has been lost — try again shortly.

The "awaiting verification" state

On a trial workspace, a document shows status awaiting verification when none of the workspace's admins has verified their email address yet. Uploads still land and nothing is lost — processing simply doesn't start until an admin clicks the link in the confirmation email. Once verified, every parked document resumes automatically: documents that had already finished are restored to how they were, and the rest continue through the pipeline and bill normally. This only affects trial workspaces, and the hold follows the workspace's own admin account, not yours — paid plans and firm-managed workspaces aren't held this way. See Verifying your email if you haven't received the confirmation email.

Upgrading to a paid plan also releases parked documents, even if nobody has clicked the verification link — the same automatic resume runs the moment your plan changes. Buying a top-up on a workspace that's still on the trial plan does not release them: the hold is tied to being on the trial tier, not to your credit balance, so top-up alone leaves parked documents parked until either the plan changes or an admin verifies.

Contacting support

If you're stuck — a validation message you don't understand, a document that keeps failing, or anything account-related — email [email protected]. Including the document name and, if you have it, the exact error message from the pipeline errors page helps get to an answer faster.

See also: Reference for the full document status glossary, and Reviewing documents for fixing a flagged document.

Looking for the developer/API reference? See /api/docs-guide. Can't find an answer? Email [email protected].