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 and 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.