Skip to content

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