---
title: "Error codes · Alran Code Docs"
url: https://alran.dev/en/docs/errors
locale: en
updated: 2026-11-16
---

[Docs](https://alran.dev/en/docs)Reference

# Error codes

Every error the terminal shows carries a number. This is what each one means and what you can do about it.

On this page

[What do the runtime error codes mean?](#runtime) [The same number, different meanings](#collide) [Where the numbers come from](#sources) [Exit codes of alran exec](#exec) [Exit codes of the account commands](#account) [Machine-readable output](#machine) [What to check first](#check) [Common questions](#faq)

## What do the runtime error codes mean? {#runtime}

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 {#collide}

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 {#sources}

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](https://alran.dev/en/docs/byok)).

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 {#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 {#account}

`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](https://ai.ottili.one) |

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 {#machine}

`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:

| 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 {#check}

| 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](https://alran.dev/en/docs/troubleshooting) lists the usual suspects. To [report a bug](https://alran.dev/en/docs/troubleshooting#report), add your `alran --version`, the interface you used (TUI, `exec`, ACP) and a minimal reproduction.

## Common questions {#faq}

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.

[PreviousConfiguration and data](https://alran.dev/en/docs/config) [NextTroubleshooting](https://alran.dev/en/docs/troubleshooting)
