> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ancha.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These docs describe the Ancha CLI, npm package @ancha-labs/cli version 0.1.4, and the hosted workspace at app.ancha.io. Coding agents should start at https://docs.ancha.io/coding-agents. Run the CLI as `ancha` after `npm install -g @ancha-labs/cli`, or as `npx -y @ancha-labs/cli@0.1.4` without installing. Pass --json for machine-readable output, or set ANCHA_JSON=1. Every command ends with a `next:` line naming the next command. Exit codes: 0 pass, 1 a check failed or a comparison regressed, 2 usage, config or authentication error, 3 infrastructure error, 4 unimplemented endpoint with --strict.

# Errors and exit codes

> Every error code the ancha CLI reports, the exit code it maps to, what usually causes it and what to do.

Errors print to stderr as `error[CODE]: message` with a `hint:` line that names the next command. With `--json`, they print to stdout as one object:

```json theme={null}
{"error":{"code":"USAGE","message":"unknown run \"run_nope\"","hint":"see .ancha/runs/"}}
```

`ancha schema error` prints the schema of this object.

## Exit codes

| Code | Meaning |
| - | - |
| `0` | Success. |
| `1` | Checks failed, the pass rate was below `min_pass_rate`, or a comparison regressed. |
| `2` | Usage, config, scene or authentication error. Fix the input; retrying will not help. |
| `3` | Infrastructure error. Not an agent failure; read the message and retry. |
| `4` | `ancha run --strict` saw a call to an endpoint a replica does not implement. |

For `ancha run`, when several apply, `3` wins over `4` and `4` wins over `1`. Playground runs use `0` for completed, `2` for stopped or not ready and `3` for execution errors.

## Error codes

| Code | Exit | Typical causes | What to do |
| - | - | - | - |
| `USAGE` | 2 | Unknown flag or argument, unknown run or baseline name, missing agent command, no `ancha.yaml`, unsupported `connect` language, not signed in for `secrets`, an `--idempotency-key` reused for a different run, a world command with no scene or no checks to apply. | Read the hint. `ancha <command> --help` lists the flags. |
| `CONFIG_INVALID` | 2 | Unknown or invalid field in `ancha.yaml`, unknown `{{template}}` in `agent.env`, invalid `agent.execution`, Google Ads in a container or playground run, `ancha world gen` without `OPENROUTER_API_KEY`, a native SQLite module that npm did not build. | Fix the file named in the hint. Every problem is listed with its path. |
| `SCENE_INVALID` | 2 | A scene or world file that does not match the format, an unknown ref, an invalid duration or timestamp. | Run `ancha scene validate <file>`. See [Test file](https://docs.ancha.io/reference/test-file.md). |
| `AUTH_INVALID` | 2 | The hosted server rejected the API key, or needs one. | Run `ancha login` again, or set `ANCHA_API_KEY` to a current key from **Settings**. `ancha whoami --verify` tests the key. |
| `CHECKS_FAILED` | 1 | Checks failed. | `ancha explain latest`. |
| `UNIMPLEMENTED_ENDPOINT` | 4 | A coverage gap under `--strict`. | `ancha twins coverage <tool>`. |
| `SERVER_UNREACHABLE` | 3 | DNS, connection or timeout failure, an address that is not an Ancha server, or a hosted workspace that is still starting. | Check `--server-url`, `server.url` and `ANCHA_SERVER_URL`; `ancha whoami` shows the saved server. |
| `SERVER_START_FAILED` | 3 | `ancha run` could not start its local server. | Check that the port is free and Node.js is 24 or later. |
| `AGENT_SPAWN_FAILED` | 3 | The agent command could not be started. | Check `agent.command` and `agent.cwd`. |
| `AGENT_UNREACHABLE` | 3 | An endpoint agent never became ready, or the local container runtime is missing a requirement such as Python 3.12. | Check `ready_url` and `x-ancha-env-id`, or run `ancha execution doctor`. |
| `ENV_NOT_FOUND` | 3 | The environment or live world expired, was removed, or its local server stopped. | Create a new one, for example `ancha world up --json`. |
| `SESSION_CONFLICT` | 3 | A trial or environment was used in a state that does not allow the operation, or a run with the same `--idempotency-key` is still going. | Retry with a fresh run, or `ancha wait <id>` for the running one. |
| `SESSION_UNAUTHORIZED` | 3 | A stale or wrong trial token. | Use the variables of the current trial. |
| `INTERNAL` | 3 | An unexpected error, or an unexpected answer from a hosted server. | Retry; if it repeats, report it with the message. |

## Errors inside a run

Problems during a trial do not stop the run. They appear in the summary:

| Where | Meaning |
| - | - |
| `agentIssues` | The agent crashed, exited non-zero or timed out. It is still graded on what it did. |
| `harnessIssues`, `invalidTrials` | Ancha itself failed in a trial. The trial does not count as an agent failure, and the run exits `3`. |
| `coverageGaps` | Calls to unimplemented endpoints. Exit `4` only with `--strict`. |

See [Troubleshooting](https://docs.ancha.io/troubleshooting.md) for common situations.


## Related topics

- [World lifecycle](https://docs.ancha.io/cli/world-lifecycle.md)
- [CLI overview](https://docs.ancha.io/cli/overview.md)
- [For coding agents](https://docs.ancha.io/coding-agents.md)
- [ancha playground](https://docs.ancha.io/cli/playground.md)
- [ancha run](https://docs.ancha.io/cli/run.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.