Errors and exit codes - Ancha

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:

{"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.
`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 for common situations.