Troubleshoot knowledge sources
Diagnose common source, processing, scope, capacity, and retrieval problems without masking the underlying cause.
2 min read
- Project
- Knowledge
- Select a source
Begin with the source row and detail view in Knowledge. Its status, configuration, and retained content identify which layer needs attention.
Find whether the failure is admission, indexing, assignment, or retrieval before changing an agent.
- Finish with
- One responsible layer to fix, not a chain of retries
Use status, stored error, pages/folders, assignment, and capacity state to locate the responsible layer. Do not repeatedly retry before identifying it.
| Symptom | Likely checks | Correct next action |
|---|---|---|
| Website source is waiting | Is it explicitly awaiting start? Was the URL and authority attestation reviewed? | Review configuration and select Start Scraping. |
| Source remains pending or processing | Is a job active? Is a rate or capacity limit pausing it? | Check progress and history; wait, cancel a genuinely stuck run, then retry once idle. |
| Source is in error | What does the stored error message say? Is the URL/file/text valid? | Correct the stated cause and re-sync. |
| Expected page is missing | Was it in crawl scope? Was it discarded or unclassified? Is the preview fallback truncated? | Inspect Pages and Folders; adjust scope or improve the authoritative source. |
| Agent does not use the source | Is it ready and assigned? Does it contain a clear answer? | Fix status or assignment first, then test a direct question. |
| New run is blocked | Is a daily run limit, rolling indexing budget, or indexed capacity review active? | Wait for the window, reduce/prioritize content, or complete the capacity selection. |
| Recurring refresh did not run | Is it due, idle, attested, and allowed by capacity/rate limits? | Check last synced time and history; resolve the blocking condition. |
Before escalating
Capture the source name, source type, status, visible error, last synced time, intended URL or file name, whether the source is assigned to the affected agent, and a synthetic example question. For a website issue, also record selected mode, depth, maximum pages, and whether the expected page appears in Pages or discarded-content metrics.
Avoid sharing credentials, private customer text, access tokens, or proprietary prompts in a support request. A concise synthetic reproduction is usually enough to start diagnosis.
Last updated on