Dokumentation durchsuchen
Fehlerbehebung
Symptom, Ursache, Lösung für echte BMAD+-Fehler: abgelehnte Installationen und Updates, veraltete Sperren, doctor-Fehler, veraltete Anweisungen, Schwärme zur Freigabe, rote Gates.
Auf dieser Seite
Diese Seite ist nach dem geordnet, was du siehst, nicht nach Befehl. Jede Zeile nennt einen Fehler, den es im Code gibt, mit der Meldung, wie sie ausgegeben wird, der Ursache und der kürzesten Lösung. Meldungen der CLI sind immer englisch, auch wenn der Installer deine Sprache spricht; sie sind wörtlich zitiert, damit du sie suchen kannst. Braucht eine Zeile mehr, verweist die letzte Spalte auf die Befehlsseite.
Erste Hilfe: drei Befehle
Nur lesend; keiner verändert dein Projekt. Sie brauchen die lokale Kopie des Projekts (npm install --save-dev bmad-plus); ohne sie lass --no-install weg
npx --no-install bmad-plus --version
npx --no-install bmad-plus doctor
npx --no-install bmad-plus update-check --offlineDer erste gibt die Version des laufenden Pakets aus. doctor vergleicht das Projekt mit seinem Manifest und zeigt jede Prüfung, die kein einfaches Bestanden ist; beginne mit den Fehlern. Der dritte zeigt installierte und laufende Version, ohne das Netz zu berühren.
Installieren und aktualisieren
| Symptom | Ursache | Lösung | Details |
|---|---|---|---|
npx canceled due to missing packages and no YES option | Du hast npx --no-install benutzt, aber das Paket ist im Projekt nicht installiert: Der Installer legt es dort nicht ab. | Führe einmal npm install --save-dev bmad-plus aus oder lass --no-install weg und nutze npx bmad-plus .... | cli-overview |
This command requires a terminal. Run ... (Code 1) | Der Befehl braucht Antworten, und die Eingabe ist kein Terminal (Skript, CI, Pipe). | --yes ergänzen. | install |
Die Installation endete, aber es gibt weder CLAUDE.md noch AGENTS.md noch eine Tool-Datei. Im Log stand No AI tool detected; no instruction adapter written. | --yes rät nie ein Tool, und es wurde kein Tool-Ordner gefunden. | Erneut mit --tools claude-code (oder anderen IDs, oder all) ausführen. | adapters |
BMAD+ vX is installed; this package is vY. Run bmad-plus update first | install ergänzt Packs und Tools nur für dieselbe Version. | update ausführen, danach install erneut. | update |
Downgrade refused | Das gestartete Paket ist älter als die installierte Version. | npx bmad-plus@latest ... starten. Zum Zurückgehen aus einem Beleg wiederherstellen. | update |
Another update is in progress: <path>. oder doctor lock.stale | Eine Installation oder ein Update hält .bmad/update.lock oder starb darüber. | Warten. Läuft nichts und doctor sagt „stale“, die genannte Sperrdatei löschen und erneut versuchen. | doctor |
Confirm this exact update with --yes. dann Target: vX | update --latest meldet nur, bis du freigibst. | update --latest --yes ausführen. | update |
Update refused: automatic-updates-not-authorized. (update --auto oder update --latest --auto) | Der Richtlinienmodus ist notify, --auto ist also nicht erlaubt. | Von Hand mit --yes freigeben oder auto mit einem Bereich wählen. | update-policy |
Update refused: fresh-metadata-required | npm war für eine frische Antwort nicht erreichbar. | Verbindung prüfen und erneut versuchen; update-check --refresh zeigt, was npm sagt. | update-check |
update-check gibt unknown: registry-unavailable oder registry-retry-backoff aus | Kein Netz, oder vor weniger als einer Stunde wurde ein Fehler vermerkt. | Mit --refresh erneut versuchen. Kein Fehler: Der Exit-Code ist 0. | update-check |
Nach einem Update bleiben manche Dateien unverändert, und das Log sagt preserved (...) | Du hast sie bearbeitet, oder BMAD+ hat sie nie verzeichnet: Sie bleiben absichtlich erhalten. | Nichts zu beheben. Bei Bedarf von Hand vergleichen; --restore macht das Update rückgängig. | update |
...; rolled-back. Recovery: bmad-plus update --restore <id> ... | Ein Schreibvorgang scheiterte unterwegs; das Update hat sich selbst zurückgenommen. | Ursache beheben (Platte, Rechte, gesperrte Datei) und erneut versuchen. | update |
Install manifest is unreadable or corrupt | Das Manifest ist beschädigt. | install sichert es als .corrupt.bak und schreibt es neu; sonst die Datei wiederherstellen. | install |
External module design-skill is X but this BMAD+ expects exactly Y | Das festgelegte Skill-Pack des Design-Pakete passt nicht. | Das Paket bmad-plus neu installieren; das Projekt wurde nicht angefasst. | install |
doctor-Fehler und veraltete Anweisungen
| Symptom | Ursache | Lösung | Details |
|---|---|---|---|
doctor endet mit 1 und file.missing: Missing required file: ... | Eine von BMAD+ installierte Datei wurde gelöscht. | install erneut ausführen; es stellt fehlende Dateien wieder her und lässt deine in Ruhe. | doctor |
doctor: Fehler runtime.node | Node.js ist älter als 20.0.0. | Node.js aktualisieren. | doctor |
doctor: pack.unknown / pack.core-missing | Das Manifest nennt ein unbekanntes Pack oder hat kein Core. | Manifest wiederherstellen oder mit der Version neu installieren, die es erzeugt hat. | doctor |
doctor: file.modified oder adapter.modified (Warnung) | Du hast eine verwaltete oder Anweisungsdatei bearbeitet. | Erwartet. update behält sie; bei Bedarf von Hand vergleichen. | update |
doctor: adapter.unowned oder adapter.adopted | Die Anweisungsdatei gehört nicht BMAD+, oder ein Repository-Tool hat sie erzeugt. | Von Hand zusammenführen oder beiseiteschieben und install für dieses Tool erneut ausführen. | adapters |
doctor: runtime.python-unverified (Warnung) | Die Umgebung eines Python-Packs wurde nicht geprüft. | doctor --verify-python zum Prüfen; install --provision-python zum Anlegen. | doctor |
| Der Assistent scheint nach einem Update alte BMAD+-Anweisungen zu befolgen | Das Tool hat seine Anweisungsdatei vor dem Update geladen. | Anweisungen neu laden oder eine neue Sitzung starten (der Befehl sagt es). Die adapter.*-Zustände von doctor ansehen: Eine erhaltene Datei wurde nicht aufgefrischt. | update |
| Ein Agent ist dem Assistenten unbekannt | Die Anweisungsdatei des Tools wurde nicht geschrieben oder nicht gelesen (bei Aider nicht in dessen Konfiguration eingetragen). | --tools prüfen; bei Aider read: CONVENTIONS.md in .aider.conf.yml ergänzen. | adapters |
| Nach dem Deinstallieren bleiben Dateien | Sie waren bearbeitet oder gehören nicht BMAD+; Memory und Konfiguration bleiben absichtlich. | Selbst löschen, wenn sie weg sollen. | uninstall |
Intake, Schwarm, Nexus, Abnahme, Review
| Symptom | Ursache | Lösung | Details |
|---|---|---|---|
swarm init gibt needs approval aus und endet mit 2; kein Briefing geschrieben | Der Lauf braucht mehr Sub-Agenten als swarm.budget (Standard 26). | Einen Menschen fragen. Nach einem Ja mit --approved --seed <seed> wie ausgegeben wiederholen. Oder --n senken. | swarm |
swarm save gibt Swarm: Reply of unit U refused: ... aus | Die Antwort erfüllt den Antwortvertrag nicht; nichts wurde geschrieben. | Den Sub-Agenten erneut fragen oder die Einheit offen lassen. Die Antwort nie selbst schreiben. | swarm |
swarm tally sagt 1 of 30 units counted; 29 skipped | Nur gültige Antworten zählen; fehlende oder ungültige Einheiten werden übersprungen und genannt. | check ausführen, dann briefs, und die offenen Einheiten noch einmal fragen. | swarm |
intake plan endet mit 2 und not ready, Must-haves still open: ... | Mindestens eine Pflichtfrage ist unbeantwortet. | Die aufgelisteten Fragen stellen, Antworten mit record festhalten, erneut planen. | intake |
Intake: <answers> does not answer this intake: ... | Der Fragebogen hat sich nach dem Festhalten von Antworten geändert. | record --reset ausführen, dann erneut fragen. | intake |
studio prepare gibt needs-input aus und endet mit 2 | Der Workflow braucht eine Anfrage oder eine Eingabedatei. | --request oder --input ergänzen. | studio |
Dev Studio: Dev Studio is not installed. Run bmad-plus install --packs core,dev-studio | Das Pack ist nicht in diesem Projekt. | Das Pack installieren. | studio |
nexus: Another mutation owns writer.lock; inspect before explicit recovery. | Ein anderer Nexus-Befehl läuft, oder einer wurde abgebrochen. | Warten; bei Abbruch inspect, dann recover-lock. | nexus |
nexus verify endet mit 1; Stale evidence: checked artifacts or write scope changed. | Dateien haben sich nach der Prüfung geändert. | verify vor accept erneut ausführen. | nexus |
uat gate endet mit 2 (awaiting), oder uat read gibt <id>: no run yet aus | Für dieses Protokoll gibt es keinen beendeten Lauf. | Die Protokollseite bis zum Ende durchspielen und die Ergebnisse importieren oder servieren. | uat |
uat gate endet mit 3 (stale) | Der jüngste Lauf antwortete auf eine andere Revision des Protokolls. | Das Protokoll nach der Änderung erneut durchspielen. | uat |
review gate endet mit 2 (incomplete) | Abdeckung oder Befunde fehlen, oder das Review hielt früh an. | Mit review continue abschließen; run.stop nur dann auf completed setzen, wenn es stimmt. | review |
review continue endet mit 3 (moved) | Code oder Regeln haben sich seit dem Versiegeln des Umfangs geändert. | Neuen Umfang versiegeln, dann review compare <new> --since <old>. | review |
assurance: BMAD_PLUS_ASSURANCE_KEY must hold at least 32 characters | Der Signaturschlüssel ist zu kurz. | Einen Schlüssel mit 32 oder mehr Zeichen verwenden oder ihn entfernen. | assurance |
assurance verify endet mit 1 | Der Case ist nicht belegt: schmutziger Baum, veraltete, fehlgeschlagene oder fehlende Prüfung oder, falls du --ledger-head übergeben hast, ein Ledger, das diesen Eintrag nicht mehr enthält. | Fehlende Prüfungen ausführen, committen und erneut verifizieren. | assurance |
Memory
| Symptom | Ursache | Lösung | Details |
|---|---|---|---|
memory status gibt Not installed. Run: npx bmad-plus install (select Memory pack) aus | Das Projekt hat kein .agents/memory/. | Das Memory-Pack installieren. | memory |
memory export gibt Global brain not found. Nothing to export. aus | Kein globales Brain in ~/.bmad-plus/brain. | Das Memory-Pack in irgendeinem Projekt installieren, um es anzulegen. | memory |
mem recall scheitert: Evidence ranking supports project-local lexical recall only. | --ranking evidence mit --scope portfolio. | Den Projektumfang verwenden. | mem |
mem observe scheitert: Outcome source is not an accepted task with current independently verified evidence. | Die Nexus-Aufgabe ist weder geprüft noch abgenommen. | Zuerst nexus verify und nexus accept ausführen. | mem |
Memory writer lock is occupied. ... | Ein anderer mem-Schreibvorgang läuft oder wurde abgebrochen. | Warten; .bmad/memory/writer.lock nur löschen, wenn kein mem-Prozess läuft. | mem |
Tipp Immer noch festgefahren
Führe doctor --json aus und bewahre die Ausgabe zusammen mit der genauen Meldung und dem Exit-Code auf. Diese drei Angaben verlangt jeder, der dir hilft, als Erstes.
Siehe auch
- Exit-Codes jedes Befehls Die Kommandozeile im Überblick
- doctor doctor
- Der ganze Lebenszyklus Installieren, aktualisieren, deinstallieren
- Projektstruktur Projektstruktur