Troubleshooting

Troubleshooting

Map a symptom to its cause and fix.

Audience: anyone integrating or operating the service. What you will accomplish: quickly resolve the most common issues.

Empty answer in strict mode

Symptom: answer is empty (or a “no information” message) and sources is [].

This is expected behavior, not an error. In strict mode the bot refuses when no document is relevant — or when the drafted answer is not supported by the retrieved chunks.

Fixes:

  • Ingest a document that covers the question — see Ingesting documents.
  • Lower score_threshold slightly if valid questions are being rejected.
  • Switch to mode: "open" to allow general knowledge (it will be honest about provenance).

401 Unauthorized on ingest

Symptom: an ingest call returns 401.

Cause: the endpoint needs X-API-Key. DELETE always requires it (when a key is configured); other ingest endpoints require it when REQUIRE_AUTH_FOR_INGEST=true.

Fix: send a valid X-API-Key header. See Ingesting documents.

422 Validation error

Symptom: a request returns 422 with an errors[] array.

Cause: the body failed validation — for example an empty q, top_k outside 1–10, score_threshold outside 0–1, an invalid rating, or a file_name containing dots or slashes.

Fix: read errors[] — each entry names the offending field. Correct it and resubmit.

429 Too Many Requests

Symptom: a request returns 429.

Cause: you exceeded 60 requests/minute per IP.

Fix: wait the number of seconds in the Retry-After header, then retry. Watch X-RateLimit-Remaining to slow down before you hit the limit. See Errors & rate limits.

Degraded /health

Symptom: GET /health returns degraded, or GET /ready returns 503.

Cause: Redis or ChromaDB is unreachable. Chat may still respond, but conversation memory and retrieval can be impaired.

Fix (operator): check that Redis and ChromaDB are running and reachable; GET /ready returns dependency-specific detail for which one is down.

Tokens arrive all at once (streaming)

Symptom: with the streaming endpoint, the whole answer appears at the end instead of token-by-token.

Cause: a reverse proxy is buffering the event stream.

Fix: ensure the proxy does not buffer SSE; the endpoint already sets Cache-Control: no-cache and X-Accel-Buffering: no. See Streaming.

Verify your result

  • Verify: You can tell a strict-mode refusal apart from a real failure.
  • Verify: You send X-API-Key where ingest requires it.
  • Verify: You parse errors[] on 422 and honor Retry-After on 429.
  • Verify: You know to check Redis/ChromaDB when health is degraded.

Related next steps

Conversation memory