AI assistant can’t find an uploaded document: troubleshooting runbook

TL;DR — If the AI assistant cannot find a document you definitely uploaded, the most common cause is that the file exists in storage but has not finished indexing (building searchable text and metadata). Start by checking the document’s status in your app or provider dashboard, then confirm the assistant is pointed at the correct knowledge base, workspace, or folder. Reading time: ~6 min

The scenario

It’s 3:40 PM on a Tuesday. You uploaded the latest pricing PDF and an updated onboarding guide this morning, and you can see both files sitting in the dashboard. But when you ask the AI assistant, “What’s our current enterprise pricing?” it replies with something like “I couldn’t find that document” or gives an old answer from last week. Your team is sure the upload happened, your client is already testing the bot, and now you need to work out whether this is an indexing delay, a permissions issue, or the wrong content source.

Symptoms

• The file appears in the app, storage bucket, or document list, but the AI assistant answers as if it does not exist.
• The assistant says things like:
  • I couldn't find any relevant document.
  • No sources found for this query.
  • I don't have access to that file.
  • The requested document is unavailable.
• Search in the document UI returns nothing for text you know is inside the file.
• The document shows a status such as:
  • Processing
  • Indexing
  • Queued
  • Failed
• The assistant cites an older version of the document instead of the one you uploaded today.
• A scanned PDF opens fine for humans, but searches for exact phrases return no matches.
• In logs or activity history, you may see lines like:
  • ingestion completed, extraction=0 pages
  • index job failed
  • permission denied for document
  • workspace mismatch

Likely causes

Step-by-step diagnosis

1. Check whether the document finished indexing

   • Dashboard path: Documents or Knowledge Base → open the document → Status/Activity
   • If you have an API or admin tool, look for fields like status, indexed_at, pages_extracted, or error.
   • This is your problem if: the status is Queued, Processing, Indexing, or Failed, or if extraction shows 0 pages or 0 characters.
   • Jump to: ### File uploaded but indexing is still running or failed

2. Confirm the assistant is connected to the same content source where the file lives

   • Dashboard path: Assistant/Chatbot settings → Data sources/Knowledge sources
   • Compare that source with the document’s location, such as the workspace, project, folder, collection, or knowledge base shown on the document details page.
   • This is your problem if: the assistant points to a different workspace, collection, or folder than the uploaded file.
   • Jump to: ### Assistant is searching the wrong workspace, folder, or collection

3. Test whether the file contains selectable text

   • Open the document in your browser or desktop viewer.
   • Try to highlight one sentence and copy it.
   • Paste it into a plain text editor.
   • This is your problem if: you cannot select text, or the pasted result is blank or gibberish. That usually means the file is an image-only scan and needs OCR (optical character recognition, turning images into text).
   • Jump to: ### Document is image-only or otherwise not readable as text

4. Check access and sharing rules

   • Dashboard path: Documents → [document] → Access/Permissions/Sharing
   • Look for whether the file is limited to a person, team, private folder, or a service account the assistant does not use.
   • This is your problem if: the document is private to a user or team that does not include the assistant’s workspace or integration identity.
   • Jump to: ### Permissions block the assistant from reading the document

5. Rule out stale index or cache

   • Create a tiny test file named something like kb-cache-test-2026-08-10.txt with one unique line such as:

purple-lighthouse-48291

• Upload it to the same place as the missing document.
• Search that exact phrase in your app’s document search or ask the assistant for it.
• This is your problem if: the test file does not appear after indexing says complete, or the assistant still returns older content after a replacement upload.
• Jump to: ### Stale index or cached version is being used

1. Inspect processing details for file type or parser failures
   • Dashboard path: Documents → [document] → Activity/Processing details
   • Look for messages about unsupported file types, encrypted PDFs, oversized files, timeouts, or parse errors.
   • This is your problem if: you see errors like unsupported media type, encrypted document, parse timeout, or extraction failed.
   • Jump to: ### File type, size, or parsing failed

Fixes

File uploaded but indexing is still running or failed

1. In your dashboard, open the document and click Retry processing, Reindex, or the nearest equivalent in your provider’s UI.
2. If there is no retry button, delete only the document record from the app and upload the file again.
3. If the file is large, split it into smaller files by section before re-uploading.

If you have an API-based workflow, re-send the ingestion job after confirming the upload completed successfully.

⚠️ If you delete the document from the app before re-uploading, users may temporarily lose access to that content until indexing finishes again.

Verify it worked: the document status changes to Indexed, Ready, or similar, and a search for an exact sentence from the file returns that document.

Assistant is searching the wrong workspace, folder, or collection

1. Open the assistant settings: Assistant/Chatbot → Data sources/Knowledge sources.
2. Add or select the exact workspace, folder, collection, or knowledge base where the file lives.
3. Save the settings.
4. If there is a source priority order, move the correct source above older or test sources.

If your app supports per-environment content, also check whether you uploaded to staging but the assistant is running against production.

Verify it worked: ask for a unique phrase from the document and confirm the answer cites the correct file or folder.

Document is image-only or otherwise not readable as text

1. Run OCR on the file using a document tool you already use, such as your scanner software, Adobe Acrobat, or your cloud drive’s OCR/export option.
2. Save the output as a searchable PDF or plain text.
3. Re-upload the searchable version.
4. If tables are important, also export a .txt or .docx version because some parsers handle those more reliably than scanned PDFs.

If you have command-line access and use OCRmyPDF, the command is:

ocrmypdf input.pdf output-searchable.pdf

Verify it worked: you can highlight and copy text from the PDF, and the app’s search finds an exact sentence from the document.

Permissions block the assistant from reading the document

1. Open Documents → [document] → Access/Permissions/Sharing.
2. Grant access to the workspace, team, or service identity used by the assistant.
3. If the file sits in a private folder, move it to the shared knowledge folder the assistant is allowed to read.
4. Save changes, then trigger Reindex if your app requires permissions changes to refresh search visibility.

If your provider uses a service account for connectors, look for an identity name in the integration settings and grant that identity read access.

Verify it worked: the document appears in search results for users of the assistant, not just for the uploader.

Stale index or cached version is being used

1. In the document details page, use Reindex, Refresh, or Sync now.
2. If you replaced a file with the same name, upload it again with a new filename such as pricing-2026-08-10.pdf to force a fresh document ID.
3. Remove the old version from the knowledge base if both versions are present.
4. Ask the assistant for a phrase that exists only in the new file.

If your app has a cache or sync interval setting, reduce it temporarily and run a manual sync.

Verify it worked: the assistant returns the new wording, not the previous version, and cites the new filename or upload time.

File type, size, or parsing failed

1. Check the processing error in Activity/Processing details.
2. If the file is encrypted, export an unencrypted copy and upload that version.
3. If the file is very large, split it into smaller files by chapter or section.
4. If the file format is unusual, convert it to one of the most reliable formats for text extraction: .pdf (searchable), .txt, .docx, or .md.
5. Re-upload and reindex.

If you have command-line access, common conversions include:

libreoffice --headless --convert-to pdf myfile.docx
pdftotext input.pdf output.txt

Verify it worked: processing details show successful extraction with non-zero pages or characters, and search finds text from the file.

Prevention

1. Add a post-upload check that searches for a known phrase
   • After every upload, search for one exact sentence from the document before telling users it is live.

Example check phrase: "Enterprise plan invoices are due within 30 days."

1. Use unique filenames for new versions
   • Instead of replacing pricing.pdf, upload versioned names:

pricing-2026-08-10.pdf
onboarding-guide-v17.pdf

• This avoids stale references to older document IDs.

1. Prefer searchable PDFs or plain text exports

   • For scanner workflows, turn on OCR by default in the scanner or PDF tool.
   • For important docs, keep a .txt or .md export alongside the PDF.

2. Create an indexing status checklist for your team

   • Before announcing a document is available to the assistant, confirm:

Status = Indexed/Ready
Pages extracted > 0
Exact phrase search returns the document
Assistant data source matches the document location

1. Separate staging and production content clearly
   • Use distinct folder names or collections such as:

knowledge-base-prod
knowledge-base-staging

• Then verify the assistant points to the correct one in Assistant → Data sources.

1. Track failed ingestion jobs
   • In your provider’s dashboard, enable alerts or email notifications for document processing failures if available.
   • If no alert exists, review the Activity or Processing page daily for Failed jobs and retry them before users notice.

If you work through the checks above in order, you will usually find the issue before you need vendor support. If you do need to escalate, send them the document name, upload time, document status, extraction count, the assistant’s data source setting, and one exact phrase that should have matched.

This article was written by an AI system and published pending human review. Verify anything you intend to act on.