# Troubleshooting

> Symptom, cause, fix for the failures BMAD+ can actually produce: refused installs and updates, stale locks, doctor errors, stale instructions, needs-approval swarms, not-ready intakes, red gates.

Canonical: https://bmad-plus.rochetta.fr/docs/faq/troubleshooting/
Language: en
BMAD+ version: 0.23.1
Documentation reviewed: 2026-10-19
Author: Laurent Rochetta
License: MIT

BMAD+ documentation › [Questions and fixes](https://bmad-plus.rochetta.fr/docs/faq/) › Troubleshooting

This page is organised by what you see, not by command. Each row names a failure that exists in the code, with the message as it is printed, the cause and the shortest fix. Messages from the CLI are always in English, even when the installer speaks your language; they are quoted as they appear so you can search for them. When a row needs more, its last column points to the command page.

<a id="first-aid"></a>
## First aid: three commands

**Read-only; none of them changes your project. They need the project’s local copy (npm install --save-dev bmad-plus); without it, drop --no-install**

```sh
npx --no-install bmad-plus --version
npx --no-install bmad-plus doctor
npx --no-install bmad-plus update-check --offline
```

The first prints the version of the package you run. `doctor` compares the project with its manifest and prints every check that is not a plain pass; start with its errors. The third shows installed and running versions without touching the network.

<a id="install-update"></a>
## Installing and updating

**Install and update failures**

| Symptom | Cause | Fix | Details |
| --- | --- | --- | --- |
| `npx canceled due to missing packages and no YES option` | You used `npx --no-install` but the package is not installed in the project: the installer does not add it. | Run `npm install --save-dev bmad-plus` once, or drop `--no-install` and use `npx bmad-plus ...`. | [cli-overview](https://bmad-plus.rochetta.fr/docs/reference/cli-overview/) |
| `This command requires a terminal. Run ...` (exit 1) | The command needs answers and the input is not a terminal (script, CI, pipe). | Add `--yes`. | [install](https://bmad-plus.rochetta.fr/docs/reference/cli-install/#errors) |
| Install finished but there is no `CLAUDE.md`, `AGENTS.md` or tool file. Log said `No AI tool detected; no instruction adapter written.` | `--yes` never guesses a tool, and no tool folder was found. | Re-run with `--tools claude-code` (or other ids, or `all`). | [adapters](https://bmad-plus.rochetta.fr/docs/reference/adapters/) |
| `BMAD+ vX is installed; this package is vY. Run bmad-plus update first` | Install only adds packs and tools to the same version. | Run `update`, then `install` again. | [update](https://bmad-plus.rochetta.fr/docs/reference/cli-update/) |
| `Downgrade refused` | The package you run is older than the installed version. | Run `npx bmad-plus@latest ...`. To go back, restore from a receipt. | [update](https://bmad-plus.rochetta.fr/docs/reference/cli-update/#recovery) |
| `Another update is in progress: <path>.` or doctor `lock.stale` | An install or update holds `.bmad/update.lock`, or died holding it. | Wait. If nothing runs and doctor says stale, delete the named lock file and retry. | [doctor](https://bmad-plus.rochetta.fr/docs/reference/cli-doctor/#checks) |
| `Confirm this exact update with --yes.` then `Target: vX` | `update --latest` only reports until you approve. | Run `update --latest --yes`. | [update](https://bmad-plus.rochetta.fr/docs/reference/cli-update/#two-paths) |
| `Update refused: automatic-updates-not-authorized.` (`update --auto` or `update --latest --auto`) | The policy mode is `notify`, so `--auto` is not authorised. | Approve by hand with `--yes`, or choose `auto` with a range. | [update-policy](https://bmad-plus.rochetta.fr/docs/reference/cli-update-policy/) |
| `Update refused: fresh-metadata-required` | npm could not be reached for a fresh answer. | Check the connection and retry; `update-check --refresh` shows what npm says. | [update-check](https://bmad-plus.rochetta.fr/docs/reference/cli-update-check/) |
| `update-check` prints `unknown: registry-unavailable` or `registry-retry-backoff` | No network, or a failure was recorded less than an hour ago. | Retry with `--refresh`. Not a failure: the exit code is 0. | [update-check](https://bmad-plus.rochetta.fr/docs/reference/cli-update-check/#statuses) |
| After an update some files are unchanged and the log says `preserved (...)` | You edited them, or BMAD+ never recorded them: they are kept on purpose. | Nothing to fix. Compare by hand if you want the new content; `--restore` undoes the update. | [update](https://bmad-plus.rochetta.fr/docs/reference/cli-update/#what-changes) |
| `...; rolled-back. Recovery: bmad-plus update --restore <id> ...` | A write failed halfway; the update reverted itself. | Fix the cause (disk, permissions, a locked file) and retry. | [update](https://bmad-plus.rochetta.fr/docs/reference/cli-update/#recovery) |
| `Install manifest is unreadable or corrupt` | The manifest is damaged. | `install` backs it up as `.corrupt.bak` and rewrites it; otherwise restore the file. | [install](https://bmad-plus.rochetta.fr/docs/reference/cli-install/#re-running) |
| `External module design-skill is X but this BMAD+ expects exactly Y` | The Design pack’s pinned skill package does not match. | Reinstall the bmad-plus package; the project was not touched. | [install](https://bmad-plus.rochetta.fr/docs/reference/cli-install/#errors) |

<a id="doctor-and-instructions"></a>
## Doctor errors and stale instructions

**Doctor and instruction file symptoms**

| Symptom | Cause | Fix | Details |
| --- | --- | --- | --- |
| doctor exits 1 with `file.missing`: `Missing required file: ...` | A file BMAD+ installed was deleted. | Run `install` again; it restores missing files and leaves yours. | [doctor](https://bmad-plus.rochetta.fr/docs/reference/cli-doctor/#checks) |
| doctor: `runtime.node` error | Node.js is below 20.0.0. | Upgrade Node.js. | [doctor](https://bmad-plus.rochetta.fr/docs/reference/cli-doctor/#checks) |
| doctor: `pack.unknown` / `pack.core-missing` | The manifest names an unknown pack or lacks Core. | Restore the manifest, or reinstall with the version that created it. | [doctor](https://bmad-plus.rochetta.fr/docs/reference/cli-doctor/#checks) |
| doctor: `file.modified` or `adapter.modified` (warning) | You edited a managed or instruction file. | Expected. `update` will keep it; compare by hand when you want new content. | [update](https://bmad-plus.rochetta.fr/docs/reference/cli-update/#what-changes) |
| doctor: `adapter.unowned` or `adapter.adopted` | The instruction file is not BMAD+’s, or a repository tool generated it. | Merge by hand, or move it aside and re-run `install` for that tool. | [adapters](https://bmad-plus.rochetta.fr/docs/reference/adapters/) |
| doctor: `runtime.python-unverified` (warning) | A Python pack’s environment was not probed. | `doctor --verify-python` to probe; `install --provision-python` to create it. | [doctor](https://bmad-plus.rochetta.fr/docs/reference/cli-doctor/) |
| The assistant seems to follow old BMAD+ instructions after an update | The tool loaded its instruction file before the update. | Reload the instructions or start a new session (the command prints this). Check `doctor` for `adapter.*` states: a preserved file was not refreshed. | [update](https://bmad-plus.rochetta.fr/docs/reference/cli-update/) |
| An agent is unknown to the assistant | The tool’s instruction file was not written or not read (for Aider, not added to its config). | Check `--tools`; for Aider add `read: CONVENTIONS.md` to `.aider.conf.yml`. | [adapters](https://bmad-plus.rochetta.fr/docs/reference/adapters/) |
| After uninstall, files remain | They were edited or are not BMAD+’s; memory and config are kept on purpose. | Delete them yourself if you want them gone. | [uninstall](https://bmad-plus.rochetta.fr/docs/reference/cli-uninstall/#reads-writes) |

<a id="orchestration"></a>
## Intake, swarm, Nexus, acceptance, review

**Gates and refusals that are not bugs**

| Symptom | Cause | Fix | Details |
| --- | --- | --- | --- |
| `swarm init` prints `needs approval` and exits 2; no brief is written | The run needs more sub-agents than `swarm.budget` (default 26). | Ask a person. After a yes, re-run with `--approved --seed <seed>` as printed. Or lower `--n`. | [swarm](https://bmad-plus.rochetta.fr/docs/reference/cli-swarm/#errors) |
| `swarm save` prints `Swarm: Reply of unit U refused: ...` | The reply does not satisfy the answer contract; nothing was written. | Ask that sub-agent again, or leave the unit missing. Never write the answer yourself. | [swarm](https://bmad-plus.rochetta.fr/docs/reference/cli-swarm/#errors) |
| `swarm tally` says `1 of 30 units counted; 29 skipped` | Only valid answers are counted; missing or invalid units are skipped and named. | Run `check`, then `briefs`, and ask the open units once more. | [swarm](https://bmad-plus.rochetta.fr/docs/reference/cli-swarm/) |
| `intake plan` exits 2 with `not ready` and `Must-haves still open: ...` | At least one must-have question has no answer. | Ask the listed questions, `record` the answers, plan again. | [intake](https://bmad-plus.rochetta.fr/docs/reference/cli-intake/#errors) |
| `Intake: <answers> does not answer this intake: ...` | The questionnaire changed after answers were recorded. | Run `record --reset`, then ask again. | [intake](https://bmad-plus.rochetta.fr/docs/reference/cli-intake/#errors) |
| `studio prepare` prints `needs-input` and exits 2 | The workflow needs a request or an input file. | Add `--request` or `--input`. | [studio](https://bmad-plus.rochetta.fr/docs/reference/cli-studio/) |
| `Dev Studio: Dev Studio is not installed. Run bmad-plus install --packs core,dev-studio` | The pack is not in this project. | Install the pack. | [studio](https://bmad-plus.rochetta.fr/docs/reference/cli-studio/) |
| `nexus`: `Another mutation owns writer.lock; inspect before explicit recovery.` | Another Nexus command runs, or one was killed. | Wait; if it was killed, `inspect`, then `recover-lock`. | [nexus](https://bmad-plus.rochetta.fr/docs/reference/cli-nexus/) |
| `nexus verify` exits 1; `Stale evidence: checked artifacts or write scope changed.` | Files changed after verification. | Run `verify` again before `accept`. | [nexus](https://bmad-plus.rochetta.fr/docs/reference/cli-nexus/) |
| `uat gate` exits 2 (`awaiting`), or `uat read` prints `<id>: no run yet` | No finished run exists for this recipe. | Play the recipe page to the end and import or serve the results. | [uat](https://bmad-plus.rochetta.fr/docs/reference/cli-uat/) |
| `uat gate` exits 3 (`stale`) | The latest run answered another revision of the recipe. | Replay the recipe after the change. | [uat](https://bmad-plus.rochetta.fr/docs/reference/cli-uat/) |
| `review gate` exits 2 (`incomplete`) | Coverage or findings are missing, or the review stopped early. | Finish with `review continue`; set `run.stop` to `completed` only when it really did. | [review](https://bmad-plus.rochetta.fr/docs/reference/cli-review/) |
| `review continue` exits 3 (`moved`) | The code or the rules changed since the scope was sealed. | Seal a new scope, then `review compare <new> --since <old>`. | [review](https://bmad-plus.rochetta.fr/docs/reference/cli-review/) |
| `assurance: BMAD_PLUS_ASSURANCE_KEY must hold at least 32 characters` | The signing key is too short. | Use a key of 32 characters or more, or unset it. | [assurance](https://bmad-plus.rochetta.fr/docs/reference/cli-assurance/) |
| `assurance verify` exits 1 | The case is unsupported: dirty tree, a stale, failed or missing check, or, if you passed `--ledger-head`, a ledger that no longer holds that record. | Run the missing checks, commit, and verify again. | [assurance](https://bmad-plus.rochetta.fr/docs/reference/cli-assurance/) |

<a id="memory"></a>
## Memory

**Memory symptoms**

| Symptom | Cause | Fix | Details |
| --- | --- | --- | --- |
| `memory status` prints `Not installed. Run: npx bmad-plus install (select Memory pack)` | The project has no `.agents/memory/`. | Install the Memory pack. | [memory](https://bmad-plus.rochetta.fr/docs/reference/cli-memory/) |
| `memory export` prints `Global brain not found. Nothing to export.` | No global brain at `~/.bmad-plus/brain`. | Install the Memory pack in any project to create it. | [memory](https://bmad-plus.rochetta.fr/docs/reference/cli-memory/) |
| `mem recall` fails: `Evidence ranking supports project-local lexical recall only.` | `--ranking evidence` with `--scope portfolio`. | Use project scope. | [mem](https://bmad-plus.rochetta.fr/docs/reference/cli-mem/) |
| `mem observe` fails: `Outcome source is not an accepted task with current independently verified evidence.` | The Nexus task is not verified and accepted. | Run `nexus verify` and `nexus accept` first. | [mem](https://bmad-plus.rochetta.fr/docs/reference/cli-mem/) |
| `Memory writer lock is occupied. ...` | Another `mem` write is running or was killed. | Wait; delete `.bmad/memory/writer.lock` only if no `mem` process runs. | [mem](https://bmad-plus.rochetta.fr/docs/reference/cli-mem/) |

> **Tip · Still stuck** Run `doctor --json` and keep its output with the exact message and the exit code. Those three facts are what anyone helping you will ask for first.

**See also**

- [Exit codes of every command](https://bmad-plus.rochetta.fr/docs/reference/cli-overview/#exit-codes)
- [doctor](https://bmad-plus.rochetta.fr/docs/reference/cli-doctor/)
- [The whole lifecycle](https://bmad-plus.rochetta.fr/docs/guides/install-lifecycle/)
- [Project layout](https://bmad-plus.rochetta.fr/docs/reference/project-layout/)

[BMAD+ documentation](https://bmad-plus.rochetta.fr/docs/) · [Questions and fixes](https://bmad-plus.rochetta.fr/docs/faq/)

[Source on GitHub](https://github.com/lrochetta/BMAD-PLUS)