​

Knowledge operations runbook

Use this runbook when Knowledge sources fail to process, become stale, or do not retrieve as expected.

​

1. Locate the Knowledge Base/source

Confirm owner, Project/organization context, source type, and current processing state.

​

2. Separate ingestion from retrieval

Determine whether the problem is:

• upload/source access
• extraction
• chunking
• embeddings/indexing
• permissions
• retrieval
• reranking
• model interpretation

Do not rebuild the entire index when the failure is only an authorization issue.

​

3. Check indexing workers/providers

If many unrelated sources are stuck in processing/indexing, inspect worker queues and embedding/index provider health.

​

4. Retry failed ingestion

Retry only after confirming the source remains valid and the original failure condition is likely resolved.

​

5. Rebuild or recalculate indexes

Use re-index/re-embedding operations when the index itself is stale or configuration changed. These actions can be expensive; avoid applying them platform-wide without evidence.

​

6. Inspect retrieval

For a ready source that is not returned:

• confirm requester permission
• test a distinctive query
• inspect candidate results when available
• inspect filtering/reranking
• check result/context limits

​

7. Handle stale connected sources

For repositories or connected sources, refresh the upstream revision and confirm the integration still has access.

​

8. Remove duplicates/orphans

Operational cleanup can remove orphaned indexing/storage records when the active backend explicitly identifies them. Do not delete healthy user sources based only on similar names.

​

9. Escalate widespread failure

Create/update an incident when extraction/indexing/retrieval is degraded across many sources or organizations.