A Knowledge source failed to process
A source that failed carries the reason on its own record, and the reason sorts into four families: the file was refused before it was stored, extraction produced nothing usable, the work timed out or the service was unavailable, or the content itself was flagged. Only the last leaves a recoverable source — the others need a different file.
What the symptom looks like#
- Refused at upload
- No source appears at all, and the message names the problem: an unsupported type, a size ceiling, or a file signature that contradicts the extension.
error- The source exists with a reason recorded and a passage count of zero. It contributes nothing to any answer.
needs_review- The source exists and was indexed, but a scanner warning or a contradiction is outstanding. Not a failure — a decision waiting.
- Still processing
- Work is genuinely in progress, or the media timeout has yet to expire. It resolves to
activeorerror, never stays here.
Read the reason before doing anything else. Three of these four states are self-describing on the record, and the fourth resolves itself within minutes.
What it means#
Nothing was indexed. A failed source has no passages, so it is not quietly contributing partial material to answers — the design refuses half a document on purpose, because half a document answers confidently about the half it has. Existing answers and other sources are unaffected.
The causes, most likely first#
| Cause | Repair |
|---|---|
| An unsupported type — a spreadsheet, a Word document, an archive | Export the reference material as Markdown or plain text, or use Files and data, which reads a wider set of formats for a different purpose |
| The file signature does not match the extension | Open it and re-save from the application that owns the format. A renamed file is refused rather than half-parsed |
| Over the size ceiling for its type | 5 MB text, 50 MB PDF, 15 MB image, 250 MB video. Split the document, or extract the section that is actually reference material |
| No usable text — a scan with no text layer, an unreadable image | Re-export from the original with text, or type the clauses that matter as entries |
| The media timeout expired — usually a long video | Trim it, or supply a transcript as a text source instead. Six minutes is the default ceiling |
| The extraction service was unavailable, or the AI allowance was spent | Retry once the allowance resets. A whole batch failing at once points here rather than at the files |
| Warnings or a contradiction were found | Not an error. Review the warnings, or resolve the conflict |
| The stored file no longer matches its hash | The source is parked with an integrity failure. Delete it and upload the file again from a known-good copy |
What Connect completed#
- Checked the declared type against the file's first bytes and applied the ceiling for that type.
- Stored the original file and recorded its SHA-256 hash, so the artefact is still there to inspect.
- Created the source record with the title, authority, category and scopes given at upload.
- Attempted extraction, and wrote the failure reason onto the record rather than discarding it.
- Logged the attempt with the source, its type and its authority, so a pattern across several files is visible.
What Connect did not complete#
- No passages were built, so nothing from this file can be retrieved.
- No contradiction check ran, because there was no text to compare.
- The source did not become
active, and answers continue exactly as they did before the upload. - Nobody was notified beyond the record and the log — a failed upload does not raise an item in Needs You.
What you can do#
Read the reason on the source, then look at the extracted text if there is any.
Result Empty text with a clean status is the scanned-document case; text that is present but garbled is an export problem, not a Connect one.
Fix the file at its origin and upload the corrected version.
Result Different bytes mean a new source, so delete the failed one — otherwise the list fills with attempts.
For a document that will not cooperate, lift the part that matters into a typed entry.
Result Three sentences with an authority-carrying category answer more questions than a forty-page file nobody can parse.
Re-index rather than re-upload when the file is fine and something else was wrong.
Result Re-indexing works from the stored original and re-runs extraction and the scans, which is the right move after an allowance reset.
What an administrator can do, and when to escalate#
- Check the AI allowance and the model configuration if several sources failed within the same period.
- Check the configured size ceilings, which are settings rather than fixed limits.
- Look at whether failures cluster by type — every PDF failing while text files succeed points at the extraction bridge, not at the documents.
- Re-index a batch after a service problem is resolved, rather than asking people to upload everything again.
Escalate when integrity mismatches appear on files nobody has touched, or when sources of every type fail regardless of size. Both suggest the stored-file layer rather than any individual document, and neither is fixed by trying another export.
Questions#
Does a failed source cost anything?
Extraction that ran before failing consumed model usage, which is metered against the workspace's AI allowance like any other model call. A file refused at upload — wrong type, too large, bad signature — costs nothing, because those checks happen before any model is involved.
Can I retry automatically?
Re-indexing is a deliberate action rather than a background retry. That is on purpose: an automatic retry loop against a document that cannot be read burns allowance quietly and hides the real problem, which is that the document needs replacing.
The source says needs_review, not error. Is that the same problem?
No, and the difference matters. error means nothing was indexed. needs_review means the material was indexed successfully and something in it needs a human decision before it is allowed to answer. The second is a queue to work, not a fault to fix.