> ## 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. # Troubleshooting > Fixes for common problems with Ancha 0.1.4: installing, connecting an agent to the tools, variables the agent did not get, checks that fail unexpectedly, timeouts, coverage gaps, comparisons, the hosted workspace, live worlds and playgrounds. Exit codes and error codes are in [Errors](https://docs.ancha.io/reference/errors.md). Every error ends with a `hint:` line that names the next command; try it first. ## Install and setup > [accordion] npx can't find the CLI by its short name > > There is no package called `ancha` on npm. With npx, use the full package name: `npx -y @ancha-labs/cli@0.1.4 `. The short name works only after `@ancha-labs/cli` is installed globally (`npm install -g @ancha-labs/cli`) or in the project (`npm install --save-dev @ancha-labs/cli`). The instruction files `ancha init` writes say the same. > [accordion] doctor says: fail node: Node >=24 is required > > Ancha needs Node.js 24 or later. Check with `node --version`, then switch, for example with `nvm install 24 && nvm use 24`. > [accordion] CONFIG\_INVALID: Ancha's SQLite module (better-sqlite3) has no native binary for this Node > > npm skipped the module's install script, or Node was upgraded since the install. The hint gives the exact command: `npm install -g --allow-scripts=better-sqlite3,esbuild @ancha-labs/cli`. For a project install, approve the scripts with `npm install-scripts approve better-sqlite3 esbuild`, then `npm rebuild better-sqlite3`. > [accordion] npm install fails building better-sqlite3 > > The CLI depends on `better-sqlite3`, which downloads a prebuilt binary for your platform. Where none exists, npm builds it from source and needs a C/C++ toolchain: Xcode Command Line Tools on macOS, or `build-essential` and Python on Linux. > [accordion] error\[USAGE]: no ancha.yaml here > > Run `ancha init` in your agent's project. It writes `ancha.yaml` with the start command it finds in `package.json`, a Procfile, `pyproject.toml` or the Dockerfile. When it finds none, pass `--agent ""`. ## The agent and the tools > [accordion] error\[USAGE]: no agent command to run > > `ancha init` found no start command in your project, so `ancha.yaml` has none. Set `agent.command` in `ancha.yaml`, or pass `--agent ""`. > [accordion] doctor warns: Successful native \ API access was not observed > > The agent ran, but no successful call reached that tool. It is probably calling the real service, or not reading the variables Ancha sets. Point its client at the tool URL and credentials from the environment; `ancha connect --lang ts` prints the settings. A clean exit or a healthy server does not count as access. The warning does not change `doctor`'s exit code. > [accordion] The agent can't find its API key or another variable > > `ancha run` gives the agent a base set from your shell (`PATH`, `HOME`, locale and the like), Ancha's variables and the tools' variables, and nothing else. `ancha explain` says how many variables were withheld. Name the ones the agent needs under `agent.pass_env` in `ancha.yaml`, or pass `--pass-env NAME` for one run. `--inherit-env` passes everything, as 0.1.1 did, and prints a warning. See [`ancha run`](https://docs.ancha.io/cli/run#what-the-agent-gets). > [accordion] The agent gets 401 or 404 from a tool > > Send the credentials the way the real service expects them: `Bearer` for most tools, `Token token=` for PagerDuty, `DD-API-KEY` and `DD-APPLICATION-KEY` headers for Datadog, HTTP Basic for Gong and Jira, plus `LinkedIn-Version` and `X-Restli-Protocol-Version` for LinkedIn Ads. Use the full base URL from the environment; Slack's ends in `/api/`. Each [tool page](https://docs.ancha.io/tools/overview.md) has a working snippet, and `ancha connect ` prints it. > [accordion] The agent calls an endpoint and gets unknown\_method or HTTP 501 > > That endpoint is not implemented by the replica. The response carries `x-ancha-gap: 1` and a message that starts with `ancha: not implemented:`, and `ancha run` and `ancha explain` list it as a coverage gap. Check `ancha twins coverage ` for a supported way to do the same thing. Do not rewrite working code to satisfy a replica that lacks an endpoint. ## Checks > [accordion] A trace check fails although the agent made the call > > Trace patterns match the method and the path. Paths are relative to the tool's base URL and exclude the query string. Use `*` as the method when the HTTP verb does not matter; Slack's SDKs call every method with `POST`, while plain `fetch` code often uses `GET`. `ancha explain` lists the calls the agent made. > [accordion] A slack.message check fails although the reply is there > > Read `actual` in `ancha explain`. It counts the bot's messages in the channel and in the thread, which tells you whether the reply went to the wrong thread, the wrong channel or had the wrong text. `in_thread_of` counts replies only, not the parent message, and `text_contains` ignores case. > [accordion] A slack.message check passes when it should not > > State checks count starter data too. Without `from`, a message from the starter history can satisfy the check. Set `from: $bot`, or the ref of the user your agent posts as. > [accordion] Judge checks are skipped > > The summary says `judge grading skipped` with `Judge skipped: OPENROUTER_API_KEY is not configured.` Export `OPENROUTER_API_KEY` in the shell that runs `ancha run` or `ancha check`. A skipped check never passes, so a required one fails its trial; keep advisory rubrics out of `pass`. ## Runs > [accordion] The trial says exit=timeout > > The agent ran past the scene's `timeout` and was stopped. The starter scene allows 10 seconds; the default for new scenes is 5 minutes. Raise `timeout` in the scene, or make the agent finish. `ancha explain` shows the end of its log. > [accordion] The run exits 3 or reports invalid trials > > Ancha itself failed in at least one trial, so those trials are not counted as agent failures. Read `harnessIssues` in the summary, fix the cause if it is local (ports, disk, Docker), and run again. > [accordion] --compare says regressed although the scene's pass rate did not drop > > Every required check is compared, not only the scene. A check whose pass rate fell is listed first as `dropped`, and the run exits `1`, even when another check improved and the scene's rate held. Fix the dropped check, or save a new baseline if the drop is intended. > [accordion] --compare is refused > > A comparison needs the same scenes, with the same content and checks, as the baseline. If you changed a scene, save a new baseline. A baseline with invalid trials cannot be used either. Use the same `--out` for `run`, `baseline` and `explain` if you changed it. > [accordion] error\[USAGE]: baseline "before" already exists > > Baselines are never overwritten by accident. Pick another name or pass `--force`. > [accordion] error\[USAGE]: this --idempotency-key was used for a different run > > An idempotency key belongs to one run definition: the same scenes, agent and options. Reuse a key only to retry the exact same command. Use a new key for a new run. > [accordion] explain, report or logs can't find the run > > `latest` points at the newest completed run in `.ancha/runs`. If you passed `--out` to `ancha run`, pass the same `--out` to `explain`, `report`, `logs`, `status` and `wait`. > [accordion] A long run ties up the terminal > > Start it with `ancha run --detach --json` and follow it with `ancha logs --follow`, `ancha status ` or `ancha wait `. Stopping `logs` or `wait` does not stop the run. ## Hosted workspace > [accordion] error\[USAGE]: hosted runs of your own agent are in private beta for this workspace > > Running your own agent inside the workspace is in private beta: **Bring your agent**, **Connect agent**, and the `ancha agent` commands that reach the workspace are refused until your workspace has access. The hint says what to do: run `ancha run` on your computer, where your worlds and results still work, or request access at [app.ancha.io/account](https://app.ancha.io/account#hosted) under **Hosted runs**. The sample agent and its runs, worlds, sandboxes, scenarios, tools, secrets and runs from your computer against hosted worlds all work. > [accordion] The console says the hosted hours for this month are used up > > A workspace has 10 hours of machine time a month, and **Settings** shows the hours used. When they are used up, the console shows a banner, the workspace keeps your data, and the machine can start again on the 1st of the next month. Until then a call to a world in the workspace answers `this workspace's hosted hours for the month are used up`. Runs on your computer are not limited, but a run whose worlds are in the workspace starts the machine and uses its hours: pass `--local`, or unset `ANCHA_SERVER_URL` and `server.url`, to keep the worlds on this computer. > [accordion] error\[AUTH\_INVALID]: ... rejected the API key, or needs an API key > > The key was revoked, is wrong, or is missing. Run `ancha login` again, or set a current `ANCHA_API_KEY` from **Settings**. `ancha whoami --verify` tells you whether the server accepts the key you have. > [accordion] Commands fail with SERVER\_UNREACHABLE > > The server cannot be reached: a wrong address, a network problem, or a workspace that is still starting. Check `--server-url`, `server.url` and `ANCHA_SERVER_URL`; `ancha whoami` shows the server commands use. A sleeping workspace wakes in seconds; retry. > [accordion] Commands use the hosted workspace when you wanted local > > `ancha run`, `ancha doctor` and `ancha world up` put their worlds in the workspace only when `--server-url`, `server.url` in `ancha.yaml` or `ANCHA_SERVER_URL` names it; a saved login alone keeps the worlds on this computer. The first line of the run says `running on hosted …` when they went there. Pass `--local` to keep one command on this computer, or remove the setting; `ancha whoami` shows which one is in effect. > [accordion] The console says the workspace is starting > > A workspace sleeps after 30 minutes without traffic and wakes in seconds. The first start takes a few minutes. The page refreshes on its own. > [accordion] error\[USAGE]: secrets live in a hosted workspace > > `ancha secrets` needs a hosted server. Run `ancha login`, or set `ANCHA_SERVER_URL` and `ANCHA_API_KEY`. Export the variable before `ancha secrets set NAME`; the value comes from your shell. ## Live worlds and generated worlds > [accordion] error\[ENV\_NOT\_FOUND]: world \ is gone > > The world's lease ran out, `ancha world down` removed it, or its local server stopped. Every `ancha world` and `ancha check` command, and every call from the agent, renews the lease (default 30 minutes; set `--ttl`). Start a new one with `ancha world up --json`, from the same directory you use for the other commands. > [accordion] error\[USAGE]: world \ has no checks to apply > > The world started from a saved world (`--world `), which has no checks. Pass the file whose checks to apply: `ancha check --env --test `. > [accordion] error\[USAGE]: --on cloud needs a workspace > > `ancha world up --on cloud` puts the world in your hosted workspace, so it needs one: run `ancha login`, or set `ANCHA_SERVER_URL` and `ANCHA_API_KEY`. Without `--on`, the world goes where `ancha run` would put it. > [accordion] error\[CONFIG\_INVALID]: world gen needs a model key > > `ancha world gen` calls a model through OpenRouter. Export `OPENROUTER_API_KEY` in the shell, then run the same command again. See [`ancha world gen`](https://docs.ancha.io/cli/world-gen). ## Playgrounds and containers > [accordion] Install Docker or Colima to run contained agents. > > `ancha execution doctor` cannot reach a Docker engine. Start Docker Desktop, OrbStack or Colima, make sure the `docker` command is on your `PATH`, or set `ANCHA_DOCKER_CONTEXT` to the context to use. > [accordion] Set up the local execution runtime before starting a playground. > > Run `ancha execution prepare` once in the project. It needs Docker with Compose and Python 3.12 or 3.13; set `ANCHA_HARBOR_PYTHON` to use another interpreter. Run it again after upgrading Ancha when `ancha execution doctor --json` reports `worldImageReady: false`. > [accordion] The agent profile says Host process · not contained > > `ancha agent add` without `--container-image` saves a host-process profile. For playground runs, update it with `ancha agent update --container-image node:24-slim` (or another image with your runtime), then `ancha agent prepare `. > [accordion] CONFIG\_INVALID mentioning Google Ads > > Google Ads cannot be used in playground runs or with container execution. Remove it from the world, or test it with `ancha run` as a local process. ## Still stuck Email [patrick@ancha.io](mailto:patrick@ancha.io) with the command, its output and `ancha --version`, or [book a call](https://cal.com/patrick-liu-me8bzn/30min). Never include API keys. ## Related topics - [Errors and exit codes](https://docs.ancha.io/reference/errors.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.