# 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.

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

BMAD+ Dokumentation › [Fragen und Lösungen](https://bmad-plus.rochetta.fr/de/docs/faq/) › Fehlerbehebung

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.

<a id="first-aid"></a>
## 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**

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

Der 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.

<a id="install-update"></a>
## Installieren und aktualisieren

**Fehler bei Installation und Update**

| 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](https://bmad-plus.rochetta.fr/de/docs/reference/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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-install/#errors) |
| 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](https://bmad-plus.rochetta.fr/de/docs/reference/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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-update/#recovery) |
| `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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-doctor/#checks) |
| `Confirm this exact update with --yes.` dann `Target: vX` | `update --latest` meldet nur, bis du freigibst. | `update --latest --yes` ausführen. | [update](https://bmad-plus.rochetta.fr/de/docs/reference/cli-update/#two-paths) |
| `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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-update-check/#statuses) |
| 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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-update/#what-changes) |
| `...; 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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-update/#recovery) |
| `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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-install/#re-running) |
| `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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-install/#errors) |

<a id="doctor-and-instructions"></a>
## doctor-Fehler und veraltete Anweisungen

**Symptome von doctor und Anweisungsdateien**

| 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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-doctor/#checks) |
| doctor: Fehler `runtime.node` | Node.js ist älter als 20.0.0. | Node.js aktualisieren. | [doctor](https://bmad-plus.rochetta.fr/de/docs/reference/cli-doctor/#checks) |
| 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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-doctor/#checks) |
| 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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-update/#what-changes) |
| 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](https://bmad-plus.rochetta.fr/de/docs/reference/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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-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](https://bmad-plus.rochetta.fr/de/docs/reference/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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-uninstall/#reads-writes) |

<a id="orchestration"></a>
## Intake, Schwarm, Nexus, Abnahme, Review

**Gates und Ablehnungen, die keine Fehler sind**

| 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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-swarm/#errors) |
| `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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-swarm/#errors) |
| `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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-intake/#errors) |
| `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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-intake/#errors) |
| `studio prepare` gibt `needs-input` aus und endet mit 2 | Der Workflow braucht eine Anfrage oder eine Eingabedatei. | `--request` oder `--input` ergänzen. | [studio](https://bmad-plus.rochetta.fr/de/docs/reference/cli-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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-assurance/) |

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

**Memory-Symptome**

| 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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-memory/) |
| `mem recall` scheitert: `Evidence ranking supports project-local lexical recall only.` | `--ranking evidence` mit `--scope portfolio`. | Den Projektumfang verwenden. | [mem](https://bmad-plus.rochetta.fr/de/docs/reference/cli-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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-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](https://bmad-plus.rochetta.fr/de/docs/reference/cli-overview/#exit-codes)
- [doctor](https://bmad-plus.rochetta.fr/de/docs/reference/cli-doctor/)
- [Der ganze Lebenszyklus](https://bmad-plus.rochetta.fr/de/docs/guides/install-lifecycle/)
- [Projektstruktur](https://bmad-plus.rochetta.fr/de/docs/reference/project-layout/)

[BMAD+ Dokumentation](https://bmad-plus.rochetta.fr/de/docs/) · [Fragen und Lösungen](https://bmad-plus.rochetta.fr/de/docs/faq/)

[Quellcode auf GitHub](https://github.com/lrochetta/BMAD-PLUS)