Knowledge Base Troubleshooting

Running into problems with your knowledge base? Here are the most common issues and how to fix them.

Document is stuck on "Processing"

After upload, every document runs through an indexing job. If a document sits on Processing for more than a couple of minutes:

1. Wait a bit longer — Large PDFs (50+ pages) can take a few minutes
2. Check for an error — A failed job flips the status to Failed with a reason; reasons like "password-protected", "unsupported encoding", or "corrupt file" are usually about the source file
3. Re-upload — If the document shows as Failed, the cleanest fix is to delete it and upload a fresh copy
4. Wait for the reconciliation cron — Even without manual action, stale Processing rows are flipped to Failed within ~30 minutes with reason "Ingestion timeout — please re-upload or re-ingest"

Document not showing up in search

If you've uploaded a document but the AI isn't finding it:

• Check the status — Make sure the row shows Ready, not Processing or Failed
• Wait a moment after upload — Even after a document flips to Ready, the agent's next search is when it actually pulls the new chunks; ask the question and the new content should be in the result
• Verify content match — Open the document and confirm the answer you're looking for is actually in there. The AI can't find what's not in your uploads
• Look for partial uploads — If the upload was interrupted (network blip, closed browser), the document may have been saved without all its content

Getting wrong or irrelevant results

If the agent is pulling answers that don't match your question:

• Be more specific — Vague questions get vague answers; include document names, dates, or specific topics
• Check the citations — Click the source pills under the answer; they show exactly which chunks the agent used. If the chunks themselves are wrong, the answer will be wrong
• Re-phrase — The agent searches semantically; sometimes a different phrasing surfaces different chunks
• Confirm the document is in the right workspace — KB is per-workspace; documents uploaded to one workspace aren't searchable from another

Upload failures

If a document won't upload:

• Check the file format — Make sure you're uploading a supported format (PDF, Word, text, or Markdown)
• Check file size — Very large files may time out during upload. Try splitting the document into smaller sections
• Try a different browser — Occasionally, browser extensions or settings can interfere with file uploads
• Re-encode — Convert to PDF if upload of a .docx keeps failing

The agent says "I don't know" but the answer is in my documents

A few causes:

• The document just finished processing — Try the question again in 30 seconds
• The chunk is too far from your phrasing — Re-phrase; semantic search depends on similarity to the source text
• The document failed to ingest fully — Check for a partial failure on the row; sometimes a 200-page PDF processes successfully but a few pages were skipped
• The system prompt is too restrictive — An admin may have written a system prompt that limits how the agent responds; check /knowledge-base/settings

The agent intentionally errs on the side of "I don't know" rather than fabricating, so a no-answer is sometimes a sign the index didn't get the content you expected.

I see "Failed" rows for documents I haven't touched recently

The reconciliation cron flips stuck-in-processing rows to Failed with a clear reason after a timeout. This is a safety net, not a bug — re-upload the failed documents.

Cross-workspace mix-up

If you're seeing answers that reference content you didn't upload to this workspace:

• Confirm you're in the right workspace — Multiple workspaces look similar in the UI; check the org switcher in the sidebar
• Report it — Per-workspace isolation is enforced at the index level. If you genuinely see cross-workspace data in the results, contact support immediately

Still stuck?

If none of the above fixes your issue, head to Help to contact support. Include:

• The document name and approximate size
• The processing status (Ready, Processing, Failed)
• The exact question you asked
• What the agent answered

This information makes it much faster to diagnose what went wrong.