Troubleshooting
| Symptom | Check |
|---|---|
| Startup cannot discover a model | Verify -base-url, /v1/models, upstream key, and -upstream-model. |
Upstream rejects max_tokens or max_completion_tokens | Confirm that the provider returns a structured 400 or 422 unsupported-parameter error naming the rejected field. Akritas retries only that explicit case and remembers the alternate field. |
| Model answers in the wrong language | Verify the normalized response_language in /health, restart after changing -response-language, and confirm that the selected model follows system instructions. The UI language does not change. |
| API returns 401 | Send the exact Authorization: Bearer <AKRITAS_API_KEY> header. |
| MCP startup fails | Validate executable path, stdio protocol, explicit allow, schema, and timeout. |
| RAG returns no context | Inspect the index and test the query with search-rag. |
| Validator preflight fails | Install the configured executable and verify the workspace module offline. |
| Apply returns conflict | The preview is stale; prepare and review a new one. |
| Run endpoint returns 503 | Audit persistence was disabled with an empty -audit-log. |
| Startup rejects audit history | Preserve the corrupt file for investigation; Akritas fails rather than silently skipping invalid records. |
Rejected HTTP responses and bounded change diagnostics are written through the standard Go logger. Raw proposal arguments are not logged.