---
title: Troubleshooting
description: "Common problems grouped by when you hit them. If none of these match, email help@anatomia.dev with your CLI version (ana --version) and the proof slug if applicable."
---

## Getting through the gate

Scan → init → setup → first pipeline run. Once you complete one end-to-end cycle, most of these go away.

<TroubleCard title="How do I know if my installation is healthy?">

Run `ana doctor`. It checks five dimensions — CLI version, scan freshness, context quality, skill enrichment, and proof chain health — and prints a single dashboard. Use `ana doctor --json` for CI or structured output. Fix any red (✗) items it surfaces before running the pipeline.

</TroubleCard>

<TroubleCard title="ana init failed">

1. Run from your project root, not a subdirectory or a worktree
2. Git must be configured: `git status` must succeed, `git config user.name` and `user.email` must be set
3. Node 22+ required (`node --version`) — declared in `package.json` but not checked at runtime, so older versions produce cryptic errors
4. If a prior init was interrupted, you'll see "Found incomplete init from a previous run" — follow the recovery steps it prints
5. If re-initializing: `ana init --force` skips confirmation prompts but still preserves your data

</TroubleCard>

<TroubleCard title="Scan missed my stack">

Install dependencies first (`npm install` / `pnpm install`). Without `node_modules/`, convention detection (formatting, import patterns) is limited — init warns you. Framework and database detection reads `package.json` dependencies directly. An empty repo with no commits limits detection — commit at least once. If tree-sitter analysis failed, init shows a warning with what was missed.

</TroubleCard>

<TroubleCard title="Scan detected the wrong database/AI SDK/framework">

Scan detects from your dependency manifest and reports the first match when multiple options exist. If a dependency is listed but unused, you'll see inaccurate detection. This doesn't affect your code — it affects what agents know about your stack. To correct: edit `.ana/context/project-context.md` (the file agents actually read for architecture decisions). To reduce noise on future scans, remove unused dependencies from your manifest. If wrong gotchas were seeded during init, edit or remove them from `.ana/skills/{name}/SKILL.md` under the Gotchas section.

</TroubleCard>

<TroubleCard title="Setup produced thin context">

Setup's quality depends on your answers. Don't describe your stack — describe your product, your users, the problem you solve. Take your time on design principles. You can always re-run: delete `setupPhase` from `ana.json` and run `ana run setup` again. See [Using ana-setup](/docs/guides/using-ana-setup) for how to give great answers.

</TroubleCard>

<TroubleCard title="Monorepo: scan covers the whole repo">

Anatomia scans the full repository, not individual packages. Init detects surfaces (packages that qualify as development targets) and generates per-surface commands. `commands.test` and `commands.build` are project-wide by default. To scope pipeline work to a specific surface, use `surfaces.{name}.commands.test` and `surfaces.{name}.commands.build`. Override with `ana config set surfaces.cli.commands.test "your-command"`.

</TroubleCard>

## Pipeline problems

<TroubleCard title="Unknown skill errors or missing agents in pipeline">

1. **Symptom:** "Unknown skill: git-workflow" or agents can&apos;t find skills/context during pipeline runs.
2. **Cause:** Your host repo&apos;s `.gitignore` blocks `.claude/` or `.ana/` directories. Worktrees inherit the gitignore — files that weren&apos;t committed are invisible to pipeline agents.
3. **Diagnosis:** Run `git ls-files .ana/skills/` — if it returns nothing, the files are gitignored and were never committed.
4. **Fix:** Upgrade to latest Anatomia (`npm install -g anatomia-cli`). Recent versions auto-detect gitignored infrastructure and force-add it during `ana init commit`. After upgrading, run `ana init commit` to persist the files.

</TroubleCard>

<ForPlatform platform="claude-code">
Claude Code users should confirm `claude` is on PATH if `ana run` cannot start an agent. Run `which claude`, then restart the terminal after installing or updating Claude Code.
</ForPlatform>

<ForPlatform platform="codex">
Codex users should confirm `codex` is on PATH if `ana run` cannot start an agent. Run `which codex`, then restart the terminal after installing or updating Codex.
</ForPlatform>

<TroubleCard title="codex not found">

1. **Symptom:** `ana run` selects Codex and exits with `codex not found`.
2. **Cause:** The Codex CLI is not installed or is not on your shell PATH.
3. **Diagnosis:** Run `which codex` from the same terminal where you run Anatomia.
4. **Fix:** Install Codex, restart your terminal, and re-run `ana doctor` before starting the pipeline.

</TroubleCard>

<TroubleCard title="Codex manifest or sandbox issues">

Codex agents use generated `.agent.toml` manifest files under `.codex/agents/`. If Codex opens the wrong instructions, complains about a missing manifest, or refuses filesystem access, re-run `ana init --platforms codex` to regenerate manifests and confirm the generated agent uses the expected sandbox mode. Pipeline builds require a sandbox that can edit the worktree; the generated configuration uses `danger-full-access` for that reason.

</TroubleCard>

<ForPlatform platform="claude-code">
Claude Code users usually recover permission failures by reviewing `platformFlags.claude` in `.ana/ana.json`. Remove stale flags, then run the same `ana run build` or `ana run verify` command again.
</ForPlatform>

<ForPlatform platform="codex">
Codex users usually recover sandbox or manifest failures by regenerating `.codex/agents/` with `ana init --platforms codex`. Check that the selected agent has an `.agent.toml` manifest and that pipeline stages use a sandbox mode with worktree write access.
</ForPlatform>

<TroubleCard title="My verify failed">

FAIL means Verify found issues — this is the pipeline working as designed. <DocsStat value="rejections" /> of our <DocsStat value="proofCount" /> proofs had rejection cycles.

1. Read `verify_report.md`. It lists every UNSATISFIED assertion with evidence.
2. Common causes: test tagged `@ana A003` but doesn't actually test what the contract says, missing test tags, tests that pass on both correct and incorrect implementations.
3. Run `ana run build` to fix. Build reads the verify report and addresses each failure.
4. Re-run `ana run verify`.

</TroubleCard>

Use `ana run learn` for proof-chain triage between pipeline cycles. Both platforms support Learn.

<TroubleCard title="My build never finishes">

1. Large specs can exceed the model's context window. Try multi-phase specs for big changes.
2. `ana work status` shows pipeline state. If build is "in-progress," the previous session may have crashed — re-open `ana run build` and it resumes.
3. Check if tests are hanging. Vitest defaults to watch mode — the test command must include `--run`.
4. If your selected platform stops responding, check your subscription status and API rate limits — these aren't Anatomia failures but they surface during pipeline runs.

</TroubleCard>

<TroubleCard title="Tests fail in pipeline but pass locally">

1. **Database or service not running.** Pipeline agents run your test command exactly as configured. If tests need PostgreSQL, Redis, or Docker — start them first.
2. **Missing environment variables.** `.env` files aren&apos;t loaded automatically in all test runners. Check that CI-required vars are set in your shell.
3. **Wrong test command detected.** Run `ana config show` — check `commands.test` (project-wide) and `surfaces.{name}.commands.test` (per-surface). Override: `ana config set commands.test "your-command"`.
4. **Prisma client not generated.** If using Prisma, run `npx prisma generate` before the pipeline. Some test setups require this explicitly.
5. **Monorepo surface mismatch.** Init may target the wrong package. See the monorepo troubleshooting card above for per-surface command overrides.

</TroubleCard>

<TroubleCard title="My finding count is huge">

Usually means the spec was too vague. Vague specs produce vague implementations, and Verify finds more to fault. Tighten the scope, write more specific acceptance criteria, and re-plan. A good contract has 15–30 assertions. Over 40 suggests the scope should be split.

</TroubleCard>

<TroubleCard title="ana work complete failed">

Must run from the main project directory on the artifact branch (usually `main`), not from inside a worktree. If using `--merge`: requires `gh` CLI, requires a PR to exist, and branch protection rules on GitHub can block the merge. If Anatomia cannot determine which GitHub merge method to use, set the repository default once: `ana config set mergeStrategy squash` (or `merge` / `rebase`), then retry `ana work complete --merge <slug>`. Without `--merge`: merge the PR on GitHub first, then run `ana work complete <slug>`.

</TroubleCard>

<TroubleCard title="An artifact says PASS but the code is wrong">

The contract was satisfied but the behavior is wrong — the contract didn't cover what matters. An assertion that checks `toBeDefined()` passes on garbage output. This isn't a system failure — the verification proved the contract was met. The contract was underspecified. Next cycle: write assertions with specific values and matchers. Check: does every assertion test the behavior users would notice if broken?

</TroubleCard>

## Configuration and state

<TroubleCard title="Wrong branch errors">

Commands that modify the proof chain (`close`, `promote`, `strengthen`) require the artifact branch (usually `main`). Read-only commands (`proof`, `audit`, `health`, `stale`, `context`) work from any branch. If you see "Wrong branch," check: are you in a worktree? Run proof-modifying commands from the main project directory.

</TroubleCard>

<TroubleCard title="I deleted .ana/ or .claude/">

**Deleted `.ana/`?** Proof chain history, archived artifacts, context, and canonical skills are gone permanently. `ana init` regenerates scan data and scaffolds but cannot recover proofs, context, design principles, or enriched skills. **Deleted `.claude/` or `.codex/`?** Platform agent delivery files are gone. `ana init` regenerates templates but enrichments need re-running setup. **Prevention:** run `ana init` instead of deleting — it refreshes everything and preserves your data.

</TroubleCard>

<TroubleCard title="I want to remove Anatomia from my project">

Remove Anatomia's generated content: `rm -rf .ana .claude/agents .codex/agents AGENTS.md`. If Anatomia created your CLAUDE.md, remove it too (check `git log --oneline CLAUDE.md`). Keep `.claude/settings.json` and `.claude/agent-memory/` if you use Claude Code — those are Claude Code native, not Anatomia. If you committed with `ana init commit`, revert: `git revert <commit-hash>`. Your source code is never modified — only infrastructure files.

</TroubleCard>

<TroubleCard title="Where did my proof go?">

Active work: `.ana/plans/active/`. Completed: `.ana/plans/completed/` and `proof_chain.json`. Run `ana proof` to see all entries. Run `ana proof <slug>` for details on a specific one.

</TroubleCard>

<TroubleCard title="GitHub CLI (gh) not working">

The pipeline creates PRs via `ana pr create`, which uses `gh` under the hood. If `gh` isn't installed or authenticated, PR creation fails but everything else works — Build, Verify, and the proof chain are independent of GitHub. Install from [cli.github.com](https://cli.github.com/), then `gh auth login`.

</TroubleCard>

<TroubleCard title="Version mismatch warning">

If `ana work status` or `ana doctor` shows a version mismatch between your CLI and the project's `anaVersion`, run `ana init` to update the project to your CLI version. This refreshes scan data and templates while preserving your context and proof chain.

</TroubleCard>

## Best practices

- **Start with a brief greeting.** "Hey" or "hi ana" lets the agent load project context before acting on your request. Complex first messages may be processed before all context files are read.
- **One agent per terminal.** Each pipeline stage starts a fresh platform session through `ana run`. Running a second agent in the same session may inherit state from the previous run, breaking the independence guarantee. Open a new terminal for each stage.
- **Let `ana work status` be the first check.** Before scoping, building, or verifying — run `ana work status`. It tells you what's in progress, what stage it's at, and what to do next. Every agent does this on startup; you should too.
- **Don't edit `proof_chain.json` by hand.** Use `ana proof close`, `ana proof promote`, `ana proof strengthen`. Manual edits can corrupt the chain — `ana proof health` reports incorrect trajectories, `ana proof audit` may skip entries. If the chain is corrupted, restore from git: `git checkout -- .ana/proof_chain.json`
- **Re-init instead of deleting.** `ana init` refreshes scan data and templates while preserving your context, skills, proof chain, and config. Deleting `.ana/` loses proof history permanently.
- **Pipeline runs can't break your code.** Build works in a git worktree — the main branch is untouched until you merge a PR. The worst a bad pipeline run produces is a PR you reject.
- **Start small.** Your first pipeline run should be a single-file fix or a feature you&apos;d normally spend 30 minutes on. Complex multi-file changes are better after you&apos;ve seen one full cycle succeed.
- **Check your test command first.** Most pipeline failures trace back to the detected test command. Run `ana config show` and verify `commands.test` before investigating further.

Still stuck? [help@anatomia.dev](mailto:help@anatomia.dev) — include your CLI version (`ana --version`) and the proof slug if applicable.

<NextCards cards={[
  {
    eyebrow: "Reference",
    title: "CLI commands",
    href: "/docs/reference/cli",
    description: "Every command, every flag, every option."
  },
  {
    eyebrow: "Browse",
    title: "Proof chain",
    href: "/docs/proof",
    description: "Browse verified pipeline runs."
  }
]} />
