Browse the documentation
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.
On this page
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.
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
npx --no-install bmad-plus --version
npx --no-install bmad-plus doctor
npx --no-install bmad-plus update-check --offlineThe 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.
Installing and updating
| 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 |
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 |
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 |
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 |
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 |
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 |
Confirm this exact update with --yes. then Target: vX | update --latest only reports until you approve. | Run update --latest --yes. | update |
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 |
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 |
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 |
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 |
...; 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 |
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 |
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 |
Doctor errors and stale instructions
| 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 |
doctor: runtime.node error | Node.js is below 20.0.0. | Upgrade Node.js. | doctor |
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 |
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 |
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 |
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 |
| 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 |
| 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 |
| 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 |
Intake, swarm, Nexus, acceptance, review
| 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 |
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 |
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 |
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 |
Intake: <answers> does not answer this intake: ... | The questionnaire changed after answers were recorded. | Run record --reset, then ask again. | intake |
studio prepare prints needs-input and exits 2 | The workflow needs a request or an input file. | Add --request or --input. | 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 |
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 |
nexus verify exits 1; Stale evidence: checked artifacts or write scope changed. | Files changed after verification. | Run verify again before accept. | 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 |
uat gate exits 3 (stale) | The latest run answered another revision of the recipe. | Replay the recipe after the change. | 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 |
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 |
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 |
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 |
Memory
| 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 |
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 |
mem recall fails: Evidence ranking supports project-local lexical recall only. | --ranking evidence with --scope portfolio. | Use project scope. | 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 |
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 |
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 CLI overview
- doctor doctor
- The whole lifecycle Install, update, uninstall
- Project layout Project layout