DocsReference
Error codes
Every error the terminal shows carries a number. This is what each one means and what you can do about it.
What do the runtime error codes mean?
When a response fails, the error panel of the terminal UI shows the reason and a line Code: <n>. That number is the runtime's own code. Your prompt is kept, so you can send it again once the cause is gone.
| Code | Name | What happened | What to do |
|---|---|---|---|
1 | INVALID_REQUEST | The request was malformed and was rejected before it ran | Correct the request; report the code if it keeps happening |
2 | NOT_FOUND | The session, agent or file it points to does not exist | Check the id, create or select the resource again |
3 | PERMISSION_DENIED | Your account may not act on that resource | Use an account, company or project with the right grant |
4 | CONFLICT | The change collided with something that already exists | Rename or remove the conflicting entry, then send again |
5 | TIMEOUT | The operation ran out of time | Send again, or raise --timeout |
6 | ABORTED | The run was cancelled | Send again if the cancellation was not on purpose |
7 | RUNTIME_UNAVAILABLE | The runtime could not be reached | Check connection and proxy, then send again |
8 | INTERNAL | An unclassified internal fault | Send again; report the code if it repeats |
42212 | USAGE_LIMIT_EXCEEDED | Your account reached its usage limit | Check /usage, add credit or switch provider, then send again |
50001 | INTERNAL_ERROR | A generic internal failure — the fallback when the runtime produces no other code | Run /retry; report the code if it repeats |
50110 | LLM_CREDITS_EXHAUSTED | The provider reports an empty balance (HTTP 402) | Add credit, or switch to another model |
50111 | LLM_RATE_LIMITED | The provider throttles requests (HTTP 429) | Wait a moment, then run /retry |
50112 | LLM_AUTH_ERROR | The provider or the gateway rejected your credentials (HTTP 401/403) | Run alran auth login, or fix the API key and endpoint of your own provider |
50113 | LLM_UPSTREAM_ERROR | The provider answered with an error | Run /retry; if it keeps happening, check the provider settings and your proxy |
50114 | LLM_MIGRATION_ERROR | The model is no longer served | Wait a moment and send it again, or switch the model with alran config model |
50150 | LLM_TPM_RATE_LIMITED | Your tokens per minute are exhausted | Wait for the window to reset, then run /retry |
50151 | LLM_CLUSTER_OVERLOADED | The provider cluster is overloaded (HTTP 529) | Run /retry, or switch model |
50200 | SAFETY_UNAVAILABLE | The content safety service could not be reached | Send again later; if it keeps happening, check the safety path and your proxy |
50201 | SAFETY_SENSITIVE | Content safety blocked the message | Revise the message before sending it again |
60001 | CORRUPTED_THINKING | The reasoning stream of the model arrived corrupted | Run /retry; report the code if it repeats |
Codes 1 to 8 and 50001 are generic. The rest name the part that failed: the limit, the provider, the safety check or the model itself. From 42212 on, the number names the area: 42212 the usage limit, 501xx the provider, 502xx the safety check, 60001 the model.
The same number, different meanings
A number can show up in three tables on this page, and it does not mean the same thing in all of them. 2 is a missing session in the table of runtime error codes, a broken command line in alran exec and a missing sign-in in an account command; the table in the section "The same number, different meanings" shows all three next to each other.
| Number | Runtime code | alran exec exit code | Account command exit code |
|---|---|---|---|
1 | INVALID_REQUEST | — | the Platform or the gateway refused the request |
2 | NOT_FOUND | the command line was wrong | sign-in needed |
3 | PERMISSION_DENIED | the configuration is broken | the account is rate limited |
4 | CONFLICT | the model or the runtime failed | the Platform is unreachable |
5 | TIMEOUT | — | the credit does not cover it |
6 | ABORTED | the run hit --timeout | — |
7 | RUNTIME_UNAVAILABLE | the run hit --max-steps | — |
8 | INTERNAL | — | — |
The exit codes 70, 130 and 141 belong to alran exec alone.
Look a number up in the table that belongs to where you saw it: in the error panel of the terminal UI it is a runtime code, in the process status it is an exit code.
The other way round, one event can have two numbers: a timeout is runtime code 5 and exit code 6, a cancellation is runtime code 6 and exit code 130.
Where the numbers come from
Three parties are in play. Your account and your credit live on the Ottili AI Platform. The gateway forwards the request and, for Werk, checks the credit; for Claude it sends the request on with your own Anthropic key. The provider is the model vendor behind it — Ottili Werk, Claude, or the one you brought yourself (your own provider).
Provider and gateway report codes of their own. Alran Code maps them onto the numbers above, so the table stays the same no matter which provider is behind it.
| Upstream code | Becomes | Meaning |
|---|---|---|
1400010161 | 50110 | The balance does not cover the request |
2056 | 42212 | The usage limit is reached |
2067 | 42212 | The token plan limit is reached and automatic credit use is off — switch automatic credit use back on, or raise the plan |
2045, 2046, 2047, 1039, 1041 | 50150 | The provider throttles tokens per minute |
If one of these shows up in a log, look up the number it maps to.
Exit codes of alran exec
alran exec ends with a number your script can branch on. Exit code 4 is a bucket: it covers every failure of the model or the runtime, and the message of the JSON output says which one it was.
| Code | Meaning | What to do |
|---|---|---|
0 | The run finished successfully | Nothing |
2 | The command line was wrong: a missing prompt, an unknown flag or an unusable model | Fix the command line |
3 | The configuration is broken | Open Alran and run /doctor |
4 | The run started, but the model or the runtime failed | Read the error object of the JSON output below: its message says what went wrong, its code names the failure |
6 | The run hit --timeout | Raise --timeout or make the task smaller |
7 | The run hit --max-steps | Raise --max-steps or narrow the task |
70 | An internal error | Report it, with alran --version |
130 | The run was cancelled | Nothing, you stopped it |
141 | The output pipe was closed early, for example by head | Let the output run to the end, or write it to a file |
The codes 1 and 5 do not occur here.
Exit codes of the account commands
alran auth, alran config, alran models, alran usage and alran billing use a different set:
| Code | Meaning | What to do |
|---|---|---|
0 | The command succeeded | Nothing |
1 | The Platform or the gateway refused the request | Read the message, then check account and model |
2 | Sign-in needed | Run alran auth login, or set ALRAN_API_KEY |
3 | The account is rate limited | Wait as long as the message says |
4 | The Platform or the gateway could not be reached | Check connection and proxy, then try again |
5 | Your credit does not cover the request, or Claude has no working Anthropic key | Add credit, or add your Anthropic key, on the Ottili AI Platform |
The two sets share the numbers 0, 2, 3 and 4, but they mean different things. 2 is a broken command line in alran exec and a missing sign-in in an account command. Branch on the command you ran, never on the number alone.
Machine-readable output
alran exec --output-format json prints one JSON document. When the run fails it carries an error object:
{
"schemaVersion": 1,
"type": "exec.result",
"status": "failed",
"error": {
"category": "runtime",
"code": "REVIEW_RESULT_MISSING",
"message": "Runtime completed without a validated code review result.",
"retryable": true
},
"durationMs": 1234
}The category says what kind of failure it was (config, runtime, internal), and retryable whether sending again can help. The exit code of the process still follows the table in the section "Exit codes of alran exec".
The code in this output is a name, not a number, and it is optional. The names the runner itself uses:
| Name | What it means |
|---|---|
REVIEW_RESULT_MISSING | The runtime finished without a code review result |
REVIEW_RESULT_INVALID | The runtime returned a code review result that is not valid |
INTERACTION_NOT_AVAILABLE | The runtime asked a question, and alran exec cannot ask |
STRUCTURED_OUTPUT_INVALID | The answer did not match the requested format |
RUNTIME_SHUTDOWN_FAILED | The runtime did not shut down cleanly |
OUTPUT_LAST_MESSAGE_WRITE_FAILED | The last message could not be written to disk |
A failed model call often carries no code at all, only the message of the provider. Read the message for what happened, and the code to recognise a failure of the runner.
The numbers of the first table are not in this output. They belong to the error panel of the terminal UI. A script has to work with the message and the code name instead.
If a test harness drives the terminal UI, it can still capture the number: set ALRAN_TUI_RESULT_PATH to a file, and every turn is appended to it as one JSON line, with the number in the code field of the error. Here the code is the number — the same field carries a name in the JSON above and a number in that file.
What to check first
| Symptom | First step |
|---|---|
| A model call fails | /status for account and model, /usage for the credit |
| The configuration looks wrong | /doctor |
| A run in CI fails | the exit code table of alran exec above, then the error object of the JSON output |
| Something is not found | check the ids: browse the sessions with alran --session |
Still stuck? The troubleshooting page lists the usual suspects. To report a bug, add your alran --version, the interface you used (TUI, exec, ACP) and a minimal reproduction.
Common questions
What do the runtime error codes mean?
When a response fails, the error panel of the terminal UI shows the reason and a line with the code number. Codes 1 to 8 and 50001 are generic, the rest name the part that failed: 42212 the usage limit, 501xx the provider, 502xx the safety check and 60001 the model.
Why does exit code 2 mean different things?
The same number shows up in three tables: in the error panel of the terminal UI it is a runtime code, in the process status it is an exit code. Exit code 2 is a broken command line in alran exec and a missing sign-in in an account command, so branch on the command you ran and never on the number alone.
How do I get machine-readable output from alran exec?
alran exec --output-format json prints one JSON document, and when the run fails it carries an error object with a category, a code and a message. The code is a name, not a number, and it is optional, while the exit code of the process still follows the exit code table of alran exec.