Troubleshooting
Missing Authentication header or a 401
Section titled “Missing Authentication header or a 401”The stored key is not valid for that endpoint. Almost always a pasted password, or a key belonging to a different provider. Check the key against the base URL you configured under Providers.
“No provider configured” / nothing generates
Section titled ““No provider configured” / nothing generates”No provider is marked as the default. Set one in Providers. The default is single-valued — setting a new one clears the previous automatically, so there is never a window with two.
The model is not found
Section titled “The model is not found”The model id does not match what the endpoint serves. Model names are
provider-specific; gpt-4o and openai/gpt-4o are not the same to every
gateway.
Answers ignore the scope
Section titled “Answers ignore the scope”The scope has no metrics or business rules, so there is nothing governed to ground on. Assign content in Admin → Scopes. An empty scope produces answers from raw table structure — which is the thing scopes exist to avoid.
The agent picks a plausible wrong table
Section titled “The agent picks a plausible wrong table”Undescribed columns. Raise trust on what is described, and describe what is not: Registry.
Connectors
Section titled “Connectors”The connection fails at creation
Section titled “The connection fails at creation”Check the host is reachable from the backend container, not just from your
machine. Container networking differs, and a host bound to localhost on the
Docker host is unreachable from inside a container.
Snowflake: npx not found
Section titled “Snowflake: npx not found”The Snowflake template runs the official MCP server, which needs npx in the
backend container.
DuckDB: file not found
Section titled “DuckDB: file not found”The path is resolved inside the container. Mount the file or its directory as a volume and use the container path.
Generic ODBC: driver not found
Section titled “Generic ODBC: driver not found”The driver must be installed on the host and pyodbc in the container.
Druid: connection refused
Section titled “Druid: connection refused”You are probably on the router port. Use the broker port, 8082 by default.
Registry
Section titled “Registry”Introspection returns nothing
Section titled “Introspection returns nothing”The connection works but the service sees no tables. Check the credentials have list permission, and that you are introspecting a database they can see — the template’s database field is where it looks.
Descriptions disappear after re-introspect
Section titled “Descriptions disappear after re-introspect”They should not — curated descriptions and trust levels survive. If they did disappear, that is a bug worth reporting.
Semantic search returns nonsense
Section titled “Semantic search returns nonsense”The embeddings were indexed with a different model than is configured now. Run Reindex embeddings in Providers.
Scope access
Section titled “Scope access”A user sees an empty product
Section titled “A user sees an empty product”No granted scope, or no primary scope. Both are set per user in Admin → Users. A user with grants but no primary lands on an empty Home.
Home is empty but Chat works
Section titled “Home is empty but Chat works”Grants exist but no primary scope is set. Chat falls back to something usable; Home does not.
Metrics and anomalies
Section titled “Metrics and anomalies”No anomalies are being flagged
Section titled “No anomalies are being flagged”Only certified metrics are watched, and only scheduled ones. Confirm the metric is certified, is on a schedule, and that the assigned anomaly profile thresholds are not so tight they never fire.
Everything is flagged
Section titled “Everything is flagged”Thresholds are too loose. Widen the window before loosening the threshold — the window decides whether a movement is signal or noise.
A DSPy change had no effect
Section titled “A DSPy change had no effect”A failed compile leaves the previous compiled version in place. Check the DSPy status.
Still stuck
Section titled “Still stuck”Include the tenant domain, the section you were in, and the message verbatim. The exact text matters — “it did not work” loses the detail that identifies which of these it was.