---
title: "Exit codes"
url: "https://docs.alisx.com/reference/cli/exit-codes/"
---
# Exit codes

What each `alis` exit code means and the error codes that accompany it. For scripts and agents that branch on the result of a command.

## Codes

| Code | Meaning | What accompanies it |
|---|---|---|
| 0 | Success. | The result on stdout. |
| 1 | Failure: invalid usage, or the remote operation failed. | Under `--json`, stdout still holds a structured failure: the final operation with `error`, or an error envelope. |
| 3 | Confirmation required. The command refused to proceed without explicit approval. | An envelope with code `PRODUCTION_CONFIRMATION_REQUIRED` (production deploy, or changing or revealing a production deployment environment's variables) or `APPROVAL_REQUIRED` (the user's automation tier gates this command). `retry` holds the exact re-run command. `alis skills publish` and `alis skills improve` also exit 3 with `remote_changed`. |
| 4 | Unauthenticated. | Run `alis login`, then retry. |
| 5 | No change. A wait reached its `--timeout` with nothing new. | `reply_timeout` from `alis specialist wait`. Not a failure. |
| 130 | `alis run` was interrupted with Ctrl-C. | |
| other | An external kill, or the exit status of the program `alis run` started. | Treat as code 1. |

## Error envelope

Pre-flight failures (before an operation exists) and refusals print one JSON envelope on stdout under `--json`:

```json
{
  "error": {
    "code": "ENVIRONMENT_SELECTION_REQUIRED",
    "message": "…",
    "retry": "alis deploy acme.shop.orders.v1 --json -e <env-id>",
    "retryArgv": ["alis", "deploy", "acme.shop.orders.v1", "--json", "-e", "<env-id>"],
    "retryCwd": "/home/me/alis.build/acme/build/shop/orders/v1",
    "agent": "…",
    "details": {}
  }
}
```

| Field | Meaning |
|---|---|
| `code` | A stable, upper-case or snake_case error code. |
| `message` | Human-readable explanation. |
| `retry` | The readable recovery command, when there is one. |
| `retryArgv`, `retryCwd` | The recovery command's arguments and working directory, when present. |
| `agent` | Instructions for a coding agent on what to do next. |
| `details` | Optional structured data, for example the deployment environments to choose between. |

Without `--json`, stdout is a human summary of the same failure.

## Error codes by exit code

### Exit 1

| Code | Meaning | Recovery |
|---|---|---|
| `ERROR` | Unclassified failure. | Read `message`. |
| `TIMEOUT` | A headless invocation (`--json`, or stdin/stdout not a terminal) overran its budget, usually a prompt nobody could answer. `details.phase` names the step. | Run `retry` once. If it repeats, `alis doctor --json` carries the command log. `ALIS_COMMAND_TIMEOUT=<duration>` overrides the budget. |
| `TTY_REQUIRED` | Bare `alis` (the TUI) was run without a terminal on both stdin and stdout. | Use subcommands with `--json`; `retry` is `alis setup status --json`. |
| `LOGIN_CODE_REQUIRED` | Bare `alis login` was run headless. | Print the URL with `alis login --json`, then `alis login <code> --json`. |
| `ACTIVE_BUILD_ACCOUNT_REQUIRED` | The session carries no active account. | `alis accounts list --json`, ask the user which account should own Build usage, then `alis accounts select accounts/<id> --json`. |
| `ENVIRONMENT_SELECTION_REQUIRED` | `-e` omitted and the product has more than one environment. | Choose from `details`; ids also come from `alis context view --json`. |
| `ENV_NOT_FOUND` | `alis run`: the product has no `.alis/.env`. | `alis environment refresh <org>.<product>.<env> --output <product>/.alis/.env`. |
| `NETWORK_UNAVAILABLE`, `network_unreachable` | This environment cannot reach the platform. Nothing was sent. | Retry once with network access; do not infer an outage. |
| `product_exists`, `service_exists` | A creation was repeated. | Follow `agent` instead of repeating the mutation. |
| `backend_outdated` | The backend predates this feature. | Retry later; for skills, use the MCP skills tools. |
| `no_answer` | `alis ask` found nothing to cite. | Rephrase as a fuller question. |
| `CONFIG_REQUIRED`, `INVALID_CONFIG` | `alis blocks install` for a dedicated-service block without, or with a malformed, `--config`. | Load the block's skill for the schema. |
| `workstation_not_found`, `workstation_ambiguous`, `workstation_failed`, `workstation_wait_timeout`, `herdr_missing`, `herdr_outdated` | Workstation commands. | See [alis workstation](https://docs.alisx.com/reference/cli/workstation.md). |
| `recipient_not_found`, `recipient_ambiguous`, `recipient_not_member`, `recipient_is_self`, `recipient_invalid`, `product_required`, `product_not_found`, `send_denied`, `ticket_resolved`, `message_too_large`, `message_not_utf8`, `message_file_unreadable`, `message_changed`, `unsupported_backend` | Specialist messaging. Every envelope says whether the message was sent. | See [alis specialist](https://docs.alisx.com/reference/cli/specialist.md). |
| `skill_exists`, `not_editable`, `nothing_to_apply`, `inputs_missing`, `invalid_generator`, `no_workspace`, `no_cases`, `harness_not_found`, `unmanaged_target`, `not_installed`, `domain_share_refused`, `not_curator`, `last_owner`, `not_owner`, `builder_not_found`, `github_not_connected`, `improve_timeout`, `improve_failed` | Skills. | See [alis skills](https://docs.alisx.com/reference/cli/skills.md). |

### Exit 3

| Code | Lifted by |
|---|---|
| `PRODUCTION_CONFIRMATION_REQUIRED` | Re-running with `--confirm-production` after explicit human approval. `--approve` and `--yes` never lift it. |
| `APPROVAL_REQUIRED` | Re-running the envelope's `retry`, which carries `--approve`, after the user approves. |
| `remote_changed` | `alis skills publish --force`, or `alis skills edit --refresh` to rebase. |

### Exit 4

| Code | Recovery |
|---|---|
| `signed_out` | The user runs `alis login`. |

### Exit 5

| Code | Meaning |
|---|---|
| `reply_timeout` | `alis specialist wait` saw no new reply before `--timeout`. |

Related: [Output contract](https://docs.alisx.com/reference/cli/output-contract.md), [Diagnose problems](https://docs.alisx.com/how-to/cli/diagnose-problems.md).