DEEN

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.

CodeNameWhat happenedWhat to do
1INVALID_REQUESTThe request was malformed and was rejected before it ranCorrect the request; report the code if it keeps happening
2NOT_FOUNDThe session, agent or file it points to does not existCheck the id, create or select the resource again
3PERMISSION_DENIEDYour account may not act on that resourceUse an account, company or project with the right grant
4CONFLICTThe change collided with something that already existsRename or remove the conflicting entry, then send again
5TIMEOUTThe operation ran out of timeSend again, or raise --timeout
6ABORTEDThe run was cancelledSend again if the cancellation was not on purpose
7RUNTIME_UNAVAILABLEThe runtime could not be reachedCheck connection and proxy, then send again
8INTERNALAn unclassified internal faultSend again; report the code if it repeats
42212USAGE_LIMIT_EXCEEDEDYour account reached its usage limitCheck /usage, add credit or switch provider, then send again
50001INTERNAL_ERRORA generic internal failure — the fallback when the runtime produces no other codeRun /retry; report the code if it repeats
50110LLM_CREDITS_EXHAUSTEDThe provider reports an empty balance (HTTP 402)Add credit, or switch to another model
50111LLM_RATE_LIMITEDThe provider throttles requests (HTTP 429)Wait a moment, then run /retry
50112LLM_AUTH_ERRORThe 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
50113LLM_UPSTREAM_ERRORThe provider answered with an errorRun /retry; if it keeps happening, check the provider settings and your proxy
50114LLM_MIGRATION_ERRORThe model is no longer servedWait a moment and send it again, or switch the model with alran config model
50150LLM_TPM_RATE_LIMITEDYour tokens per minute are exhaustedWait for the window to reset, then run /retry
50151LLM_CLUSTER_OVERLOADEDThe provider cluster is overloaded (HTTP 529)Run /retry, or switch model
50200SAFETY_UNAVAILABLEThe content safety service could not be reachedSend again later; if it keeps happening, check the safety path and your proxy
50201SAFETY_SENSITIVEContent safety blocked the messageRevise the message before sending it again
60001CORRUPTED_THINKINGThe reasoning stream of the model arrived corruptedRun /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.

NumberRuntime codealran exec exit codeAccount command exit code
1INVALID_REQUEST—the Platform or the gateway refused the request
2NOT_FOUNDthe command line was wrongsign-in needed
3PERMISSION_DENIEDthe configuration is brokenthe account is rate limited
4CONFLICTthe model or the runtime failedthe Platform is unreachable
5TIMEOUT—the credit does not cover it
6ABORTEDthe run hit --timeout—
7RUNTIME_UNAVAILABLEthe run hit --max-steps—
8INTERNAL——

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 codeBecomesMeaning
140001016150110The balance does not cover the request
205642212The usage limit is reached
206742212The 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, 104150150The 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.

CodeMeaningWhat to do
0The run finished successfullyNothing
2The command line was wrong: a missing prompt, an unknown flag or an unusable modelFix the command line
3The configuration is brokenOpen Alran and run /doctor
4The run started, but the model or the runtime failedRead the error object of the JSON output below: its message says what went wrong, its code names the failure
6The run hit --timeoutRaise --timeout or make the task smaller
7The run hit --max-stepsRaise --max-steps or narrow the task
70An internal errorReport it, with alran --version
130The run was cancelledNothing, you stopped it
141The output pipe was closed early, for example by headLet 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:

CodeMeaningWhat to do
0The command succeededNothing
1The Platform or the gateway refused the requestRead the message, then check account and model
2Sign-in neededRun alran auth login, or set ALRAN_API_KEY
3The account is rate limitedWait as long as the message says
4The Platform or the gateway could not be reachedCheck connection and proxy, then try again
5Your credit does not cover the request, or Claude has no working Anthropic keyAdd 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:

json
{
  "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:

NameWhat it means
REVIEW_RESULT_MISSINGThe runtime finished without a code review result
REVIEW_RESULT_INVALIDThe runtime returned a code review result that is not valid
INTERACTION_NOT_AVAILABLEThe runtime asked a question, and alran exec cannot ask
STRUCTURED_OUTPUT_INVALIDThe answer did not match the requested format
RUNTIME_SHUTDOWN_FAILEDThe runtime did not shut down cleanly
OUTPUT_LAST_MESSAGE_WRITE_FAILEDThe 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

SymptomFirst step
A model call fails/status for account and model, /usage for the credit
The configuration looks wrong/doctor
A run in CI failsthe exit code table of alran exec above, then the error object of the JSON output
Something is not foundcheck 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.