Uploading Documents
KB administrators upload documents through the same 3-step wizard used to create or edit a knowledge base. This page covers what happens during and after upload.
Where to upload
- Open the Apps Dashboard.
- Click the ✏️ edit pencil on the KB row.
- Navigate to Step 3: Knowledge Base in the wizard.
You can also jump directly to /apps/{id}/edit?step=3.
Uploading a single file
- Drag a file into the upload zone, OR click the zone to open a file picker.
- The selected filename appears with an × if you want to remove it before submitting.
- Click Submit to upload.
- A linear progress bar fills from 0 to 100% as the file uploads.
- PDF only — Word, Excel, PowerPoint and others are blocked at the form level. Selecting any other type triggers the toast "Only PDF files can be uploaded. Please select a PDF file."
- Per-file size limit — the upload zone displays the active limit (e.g. "PDF file up to 100 MB"). The default is 100 MB; enterprise environments may be raised higher. Oversized files are rejected before upload starts.
- Single file at a time — there is no batch upload button in the UI.
If you have many PDFs or non-PDF formats, contact your engineering team to use the backend API. See Known Limitations.
What happens after upload
Once the file is uploaded, it enters a multi-stage processing pipeline before becoming searchable. The Current Documents table on Step 3 shows the live status.
The pipeline
Each step updates the progress column. The full pipeline usually takes 1–5 minutes for a typical document.
Status values
| Status | Meaning |
|---|---|
| pending | The file is queued but processing hasn't started yet |
| processing | One of the pipeline stages is running. Progress percentage updates as it advances. |
| completed | The document is fully indexed and searchable in chat |
| failed | Something went wrong. Hover the row's status icon for the error message. |
Status polling
The table refreshes every 20 seconds while you're on the page — you don't need to manually refresh. Once a file is completed, users can immediately ask questions about it via Chat.
Common failure reasons
| Status message | Cause | What to do |
|---|---|---|
| File rejected: malware detected | The file failed the Azure Defender malware scan | Do not retry. Investigate the file source. |
| File held: scan inconclusive | The malware scan timed out or returned an unknown verdict | Try uploading again. If it persists, contact Support. |
| Extraction failed | The PDF is corrupted, password-protected, or in an unusual format | Re-export the PDF from the original source and try again. Password-protected PDFs must be unlocked first. |
| Token limit exceeded | The document is extremely large or dense | Split the document into smaller PDFs and upload separately. |
| Generic processing error | A transient backend issue | Wait a few minutes and try a fresh upload. |
KB size limits
Each KB has a soft limit on the total number of documents:
- Default: 5 documents per KB
When you try to exceed this limit, you'll see one of two messages:
Upload limit exceeded — Cannot upload N files. Current: 5/5 files.
Maximum file limit reached (5 files). Please delete some files before uploading new ones.
If you need more capacity, contact Support — the limit is configurable per environment.
Replacing an existing document
The current workflow does not allow in-place document replacement. To update a document:
- Delete the old version (see Deleting Documents).
- Upload the new version.
- Wait for processing to complete.
The new version's filename can be the same or different.
Best practices
| Practice | Why |
|---|---|
| Upload during off-peak hours | Processing competes for shared compute — uploading 20 files at lunch time will queue them up |
| Keep PDFs text-based, not scanned | OCR on scanned PDFs works but takes longer and is less accurate |
| Give files meaningful names | The filename appears in citations — Q3_2025_finance_policy.pdf is more useful than doc_v3_final_final.pdf |
| Remove personal info before uploading | Documents are indexed and searchable — don't ingest things you wouldn't want every KB user to find |
| Test with a sample question after upload | Open Chat, pick the KB, ask a known fact from the document. If retrieval works, you're done. |
Related
- Deleting Documents
- Creating an Application — initial upload during KB creation