Troubleshooting¶
HTTP 401¶
Cause: the client token does not match the service token.
Fix: use /etc/haystack/client.json from this instance. If you restored
a backup, keep api_token identical in client.json and config.json.
HTTP 409¶
Cause: documents or provider configuration are missing, or the document limit was reached. The package holds 1,000 documents.
Fix: sushi-haystack status. Confirm the documents were upserted. For
generation, confirm the provider object is present, then retry. Retrieval
still works when the provider is down.
HTTP 422¶
Cause: the input is invalid. Ids are at most 128 characters and use letters, numbers, underscores, dots, or hyphens. A document is at most 16,384 characters. An upload is at most 100 documents. A request is at most 2 MiB.
Fix: correct the payload and retry. Do not delete the database.
HTTP 502¶
Cause: the provider call failed.
Fix: check the base URL, model id, credential, and that a remote
provider is HTTPS. Restart is not required for a retrieval-only query.
Generation needs sudo systemctl restart haystack.service after you edit
config.json.
Last updated November 11, 2026 · Suggest an improvement