# Troubleshooting > Fix the common problems with installing stacks, writing a project, launching an agent and getting verify to green. Every failing command ends with a `Next:` line (or `next` in the `--json` error envelope) saying what to do, and the exit code tells you which kind of problem it is: 2 is your input, 3 is configuration, 5 is verify, 6 needs a person. [Output, JSON and exit codes](https://stacks.steamfield.io/docs/reference/output.md#exit-codes) has the full table. ## Check your setup with `stacks doctor` `stacks doctor` reports the version, platform and every path stacks uses, without contacting anything: ```sh title="Terminal" group="doctor" stacks doctor ``` ```text title="Output" group="doctor" ... Platform: darwin Config: /Users/you/.config/stacks/config.json Data: /Users/you/.local/share/stacks User entries: /Users/you/.config/stacks ... Configuration: ok ``` A broken `config.json` shows up here as a configuration error, and doctor still runs. Include its output when you report a bug. ## Installing stacks ### `stacks: command not found` after installing npm installed the package, but its global bin directory isn't on your PATH. Run `npm prefix -g` and add the `bin` directory under that path to your PATH, or skip the global install and use `npx @steamfield/stacks@latest` in place of `stacks`. ### The install fails or the CLI won't start stacks needs Node 22 or later, on macOS or Linux. Check with `node --version` and upgrade Node if it's older. ### `stacks update` fails `stacks update` upgrades a global npm install only. For any other kind of install it prints the command to run instead. With `--offline` or `STACKS_OFFLINE=1` set, it exits 2 before making a request. Exit 4 means the npm registry didn't answer; try again later. Exit 6 means npm itself failed, so run the printed command yourself to see npm's output. ## Writing a project ### `new` fails with `TargetNotEmpty` The target directory has files in it. `new` only writes into a directory that's missing or empty (one holding only `.git` and OS files such as `.DS_Store` counts as empty). Pick a new directory name. To bring stacks into a project that already has code, use [`stacks add`](https://stacks.steamfield.io/docs/guides/existing-repo.md). ### `new` fails with `ComposeConflict` inside another repository Some fragments, including `ci-github` and `git-hooks`, configure a repository root, so they refuse to go into a subdirectory of another repository. The error names the `--without` flags that avoid the conflict. Either write the project outside the repository, or drop those fragments: ```sh title="Terminal" stacks new go-cli my-cli --without ci-github,git-hooks ``` The same error comes up when two fragments you asked for conflict with each other. Drop one of them. ### A tool is listed as missing `new` checks the tools the stack and its fragments need (such as `go` or `uv`) and lists any that aren't on your PATH, in its result and in the brief. It never fails because of one. Install the tool before your agent builds, or leave out the fragment that needs it with the `--without` flag the warning names. ### An entry is listed as rejected, or a stack is missing An entry that fails to load shows up under `rejected` in `stacks list --json` with a one-line error. stacks never swaps in a lower copy silently. For your own entries, run `stacks validate` on the entry directory to see the full problem. An entry written for a newer `schema_version` is skipped with a warning; update stacks. ## Launching an agent ### No agent started, only a prompt was printed stacks prints the prompt instead of launching an agent when: - You passed `--no-launch` or `--json`. - stdin or stdout isn't a terminal (a pipe, a script, CI). - You ran stacks from inside an agent session. The agent gets its instructions on stdout instead. - An entry in the project is untrusted, such as one from a repository's `.stacks/` registry or an unsigned custom index. stacks never launches an agent on untrusted content. - No supported agent is on your PATH. Paste the printed prompt into your agent, or pick one explicitly with `--launch claude` (or `codex`, `opencode`, `cursor`, `copilot`). ### The wrong agent started stacks launches the first agent from your `agents` setting that's on your PATH, otherwise the only one it finds, otherwise it asks. Pass `--launch` to choose. `--agents` changes which config files the project gets, not which agent starts. [Use stacks with your agent](https://stacks.steamfield.io/docs/agents.md) has the order. ## Running verify ### verify fails on the first step right after `new` Until the agent writes the project, the install step has nothing to install, so verify fails. It passes once the agent has built what the brief describes. ### `NotFound` when running verify verify looks for `.stacks/manifest.json` in the current directory and every directory above it. Run it from inside the project. ### A step reports a missing command A step that exits 127 is reported as a missing command, with `failureKind: "env"`. The tool it calls isn't on the PATH verify sees. Install it, or check that the step runs in the same shell environment where you installed it. ### verify fails with `VerifyChanged` Someone edited, added or removed a verify step, or changed the manifest's `env` or `preset`, since the steps were recorded. verify runs nothing and names what changed. If you made the change on purpose, accept it from your own terminal: ```sh title="Terminal" stacks verify --accept-changes ``` If you didn't, undo the change, usually with `git diff .stacks/manifest.json` and a revert. Agents can't run `--accept-changes`; an agent that hits this should stop and ask you. [Verify](https://stacks.steamfield.io/docs/concepts/verify.md#tamper-evidence) explains how the check works. > [!WARNING] > Accept a change only after reading it. An agent that couldn't get a test to pass might have rewritten the step instead of the code. ### A serve step fails before the server starts verify refuses to start a server when something already answers on its port, because it couldn't tell your server from the old one. Stop whatever is listening there. To move the port for one run instead, set the variable the manifest uses, for example `PORT_WEB=5187 stacks verify`. A serve step also fails when its command exits before the probe passes. The command has to keep the server in the foreground. ### verify exits 0 but the project isn't done A run limited with `--only` or `--skip-tag` ends `partial`, which exits 0 and never counts as done. A sandbox project also skips steps tagged `prod` by default. Run `stacks verify --all` for the final check: green there means every declared step passed. ### verify says the tamper check was manifest-only On a fresh clone there's no state record on that machine, so verify can only compare the steps against the manifest's own copy. Running `stacks verify --accept-changes` once at your terminal records them on this machine. ### `InvalidConfig` on a manifest The manifest doesn't decode, or a newer version of stacks wrote it. Run `stacks update` (or use `npx @steamfield/stacks@latest`). If the file was edited by hand, restore it from git. ## Search and the network ### Search says `Ranked locally: API unavailable.` `search` asks the hosted API and ranks locally at the same time. When the API is slow or unreachable, you get the local ranking and this line. `--local` skips the API on purpose, and `--offline`, `STACKS_OFFLINE=1` or `DO_NOT_TRACK` do the same. ### Commands are slow on a bad network Network requests for search, stats, the signed index and the dependency allowlist are best-effort with short deadlines, and a failure never changes a command's result. To make no requests at all, add `--offline` or set `STACKS_OFFLINE=1`. Verified cached entries stay available offline. ## Installing the skill ### `skill install` fails with `TargetNotEmpty` A different `SKILL.md` is already installed, probably one you edited. stacks keeps it. Add `--force` to replace it with the bundled version. ## Getting debug logs Agent and `--json` output keeps stderr short. To see the logs, set a log file and level and run the command again: ```sh title="Terminal" STACKS_LOG_FILE=/tmp/stacks.jsonl LOG_LEVEL=debug stacks verify ``` Running the same command at a terminal without `--json` also prints the logs to stderr. Exit 1 (`Defect`) is a bug in stacks; the log file has the stack trace to report. ## Next steps - [Output, JSON and exit codes](https://stacks.steamfield.io/docs/reference/output.md): every error tag and what it means. - [Configuration](https://stacks.steamfield.io/docs/reference/configuration.md#environment-variables): every environment variable. - [Verify: the definition of done](https://stacks.steamfield.io/docs/concepts/verify.md): phases, outcomes and the tamper check.