Operator Runbooks
Investigate and retry failed ingestion
Diagnose a stuck or failed document and recover it.
When a document doesn't become searchable, use the
Ingestion Health panel (/operator/health) to diagnose
and recover it.
Diagnose
Open Command Center → Knowledge → Ingestion Health and review the four counters.
Find the document in the failed jobs table; note its organization, title, and the recorded error.
Determine whether the job is
failed (retries exhausted) or dead_letter (unrecoverable).Common causes
| Symptom | Likely cause | Action |
|---|---|---|
| Fails at parsing | Unsupported file type or a corrupt file | Re-upload a supported format (PDF/DOCX/XLSX). |
| Fails at embedding | Embedding provider unavailable, or an API key issue | Resolve the provider/config, then retry. |
| Embedding-dimension mismatch | EMBEDDING_DIMENSIONS doesn't match the indexed corpus | A configuration/migration fix; a plain retry won't help. |
dead_letter | Document deleted mid-flight or invalid metadata | Re-upload the document fresh. |
Retry
In the failed-jobs table, use Retry on the affected job and confirm.
The job re-enters the pipeline; the health counters and list refresh.
Confirm the document reaches
indexed.Retries use exponential back-off, so a transient provider issue often clears on its own. A retry only helps once the underlying cause is resolved. For a dimension mismatch or an unsupported file, fix the root cause first. See failure handling.
GP-scoped view
GP users can see and retry their own organization's failed jobs from Settings → Knowledge. Operators see failures across all tenants.