Troubleshooting
Fix the common problems with installing stacks, writing a project, launching an agent and getting verify to green.
# 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.View as MarkdownOpen in ClaudeOpen in ChatGPT
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 has the full table.
Check your setup with stacks doctor
stacks doctor reports the version, platform and every path stacks uses, without contacting anything:
stacks doctor...
Platform: darwin
Config: /Users/you/.config/stacks/config.json
Data: /Users/you/.local/share/stacks
User entries: /Users/you/.config/stacks
...
Configuration: okA 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.
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:
stacks new go-cli my-cli --without ci-github,git-hooksThe 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-launchor--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 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:
stacks verify --accept-changesIf 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 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:
STACKS_LOG_FILE=/tmp/stacks.jsonl LOG_LEVEL=debug stacks verifyRunning 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: every error tag and what it means.
- Configuration: every environment variable.
- Verify: the definition of done: phases, outcomes and the tamper check.