Troubleshooting & FAQ

The failures you are most likely to hit, and how to read them. Most "it returned nothing" problems are one of the two below.

A source looks empty

First distinguish *empty* from *broken*. Call discover and read the sync array:

status = "error"  -> the sync failed; read last_error (usually an expired PAT)
status = "ok" but count = 0 or null -> genuinely nothing indexed yet
status = "queued" | "running" -> ingestion still in progress

An error on commits/work_items with an empty result is the classic expired-credential signature. Re-authorize the provider and let the sync re-run.

401 from the Knowledge API

{ "detail": "Authentication required: provide a Bearer JWT or X-API-Key" }

You sent neither a valid Authorization: Bearer nor a matching X-API-Key. Note the Ontology Layer validates *service keys*, not user-issued JWTs — a backend caller must use X-API-Key. See Authentication.

MCP: "Not authenticated"

Your MCP session carries no user token. Run the authenticate tool (HTTP transport) or set MCP_AUTH_TOKEN (stdio). If instead you see a *service-credential* error from an ontology_* tool, the MCP server's INTERNAL_SERVICE_KEY does not match the Ontology Layer's.

404 from fetch

{ "detail": "No object for ref '<ref>'" }

The ref does not resolve for this project — it is stale, hand-constructed, or cross-tenant. Always use a ref verbatim from a search or activity hit; never build one by hand.

More questions? The Glossary defines every term, and each reference page states the exact shapes.