# Knowledge errors

Knowledge ingestion has two distinct phases: accepting and parsing a source, then creating the search index used by agents. A document can remain visible with a failed status so the failure is diagnosable.

## Symptom

An upload or URL import is rejected, a scanned PDF yields no usable text, or a document appears with failed indexing. Retrieval may return no evidence even though the source name is present.

## Cause

File type, size, extracted-text, workspace capacity, URL safety, and embedding-provider checks are enforced separately. `embedding_unavailable` means no embedding provider is available for the request. `embedding_failed` means indexing reached the provider but did not complete successfully. Private-network and redirect destinations are rejected by design.

## Verify

Check the source type, byte size, extracted text, document status, and displayed error. Confirm a URL is public and that every redirect remains public. For edits, verify whether the older document remains usable; a failed replacement is designed not to destroy the previous index.

## Recovery

Convert scanned material with OCR before uploading, reduce oversized content, or use a supported format. For a transient embedding failure, retry the upload or edit after provider availability returns. If workspace capacity is exhausted, remove unneeded knowledge deliberately or contact the workspace owner; do not repeatedly upload duplicates.

## Escalation

Escalate a reproducible failure with the safe filename or host, approximate size, document status, UTC time, and code. Do not attach confidential content unless the approved support channel asks for it. Read [Knowledge limits and troubleshooting](/docs/knowledge/limits-and-troubleshooting) and [Attach and retrieve](/docs/knowledge/attach-and-retrieve).

## Error code index

- `embedding_failed` — indexing reached the embedding step but failed.
- `embedding_unavailable` — no embedding provider is available.

Knowledge is data supplied to the agent, not a trusted replacement for the agent's authored instructions.