# Dépannage

> Symptôme, cause, solution pour les échecs réels de BMAD+ : installations et mises à jour refusées, verrous périmés, erreurs de doctor, instructions périmées, essaims à approuver, gates rouges.

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

Documentation BMAD+ › [Questions et dépannage](https://bmad-plus.rochetta.fr/fr/docs/faq/) › Dépannage

Cette page est organisée par ce que vous voyez, pas par commande. Chaque ligne nomme un échec qui existe dans le code, avec le message tel qu’il est affiché, la cause et la correction la plus courte. Les messages de la CLI sont toujours en anglais, même quand l’installateur parle votre langue ; ils sont cités tels quels pour que vous puissiez les rechercher. Quand une ligne demande plus, sa dernière colonne renvoie à la page de la commande.

<a id="first-aid"></a>
## Premiers secours : trois commandes

**En lecture seule ; aucune ne modifie votre projet. Elles demandent la copie locale du projet (npm install --save-dev bmad-plus) ; sans elle, retirez --no-install**

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

La première affiche la version du paquet que vous lancez. `doctor` compare le projet à son manifeste et affiche chaque contrôle qui n’est pas un simple succès ; commencez par ses erreurs. La troisième montre les versions installée et lancée sans toucher au réseau.

<a id="install-update"></a>
## Installer et mettre à jour

**Échecs d’installation et de mise à jour**

| Symptôme | Cause | Solution | Détails |
| --- | --- | --- | --- |
| `npx canceled due to missing packages and no YES option` | Vous avez utilisé `npx --no-install` alors que le paquet n’est pas installé dans le projet : l’installateur ne l’y ajoute pas. | Lancez une fois `npm install --save-dev bmad-plus`, ou retirez `--no-install` et utilisez `npx bmad-plus ...`. | [cli-overview](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-overview/) |
| `This command requires a terminal. Run ...` (code 1) | La commande a besoin de réponses et l’entrée n’est pas un terminal (script, CI, tube). | Ajoutez `--yes`. | [install](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-install/#errors) |
| L’installation s’est terminée mais il n’y a ni `CLAUDE.md`, ni `AGENTS.md`, ni fichier d’outil. Le journal disait `No AI tool detected; no instruction adapter written.` | `--yes` ne devine jamais un outil, et aucun dossier d’outil n’a été trouvé. | Relancez avec `--tools claude-code` (ou d’autres identifiants, ou `all`). | [adapters](https://bmad-plus.rochetta.fr/fr/docs/reference/adapters/) |
| `BMAD+ vX is installed; this package is vY. Run bmad-plus update first` | `install` n’ajoute des packs et outils qu’à la même version. | Lancez `update`, puis `install` de nouveau. | [update](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-update/) |
| `Downgrade refused` | Le paquet lancé est plus ancien que la version installée. | Lancez `npx bmad-plus@latest ...`. Pour revenir en arrière, restaurez depuis un reçu. | [update](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-update/#recovery) |
| `Another update is in progress: <path>.` ou doctor `lock.stale` | Une installation ou mise à jour tient `.bmad/update.lock`, ou est morte en le tenant. | Attendez. Si rien ne tourne et que doctor dit « stale », supprimez le fichier de verrou nommé et réessayez. | [doctor](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-doctor/#checks) |
| `Confirm this exact update with --yes.` puis `Target: vX` | `update --latest` se contente de rapporter tant que vous n’approuvez pas. | Lancez `update --latest --yes`. | [update](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-update/#two-paths) |
| `Update refused: automatic-updates-not-authorized.` (`update --auto` ou `update --latest --auto`) | Le mode de la politique est `notify` : `--auto` n’est pas autorisé. | Approuvez à la main avec `--yes`, ou choisissez `auto` avec une plage. | [update-policy](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-update-policy/) |
| `Update refused: fresh-metadata-required` | npm n’a pas pu être joint pour une réponse fraîche. | Vérifiez la connexion et réessayez ; `update-check --refresh` montre ce que dit npm. | [update-check](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-update-check/) |
| `update-check` affiche `unknown: registry-unavailable` ou `registry-retry-backoff` | Pas de réseau, ou un échec noté il y a moins d’une heure. | Réessayez avec `--refresh`. Ce n’est pas un échec : le code de sortie est 0. | [update-check](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-update-check/#statuses) |
| Après une mise à jour, certains fichiers sont inchangés et le journal dit `preserved (...)` | Vous les avez modifiés, ou BMAD+ ne les a jamais enregistrés : ils sont gardés exprès. | Rien à corriger. Comparez à la main si vous voulez le nouveau contenu ; `--restore` annule la mise à jour. | [update](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-update/#what-changes) |
| `...; rolled-back. Recovery: bmad-plus update --restore <id> ...` | Une écriture a échoué en route ; la mise à jour s’est annulée d’elle-même. | Corrigez la cause (disque, permissions, fichier verrouillé) et réessayez. | [update](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-update/#recovery) |
| `Install manifest is unreadable or corrupt` | Le manifeste est abîmé. | `install` le sauvegarde en `.corrupt.bak` et le réécrit ; sinon restaurez le fichier. | [install](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-install/#re-running) |
| `External module design-skill is X but this BMAD+ expects exactly Y` | Le paquet de compétences épinglé du pack Design ne correspond pas. | Réinstallez le paquet bmad-plus ; le projet n’a pas été touché. | [install](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-install/#errors) |

<a id="doctor-and-instructions"></a>
## Erreurs de doctor et instructions périmées

**Symptômes de doctor et des fichiers d’instructions**

| Symptôme | Cause | Solution | Détails |
| --- | --- | --- | --- |
| doctor sort avec 1 et `file.missing` : `Missing required file: ...` | Un fichier installé par BMAD+ a été supprimé. | Relancez `install` ; il restaure les fichiers manquants et laisse les vôtres. | [doctor](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-doctor/#checks) |
| doctor : erreur `runtime.node` | Node.js est sous la version 20.0.0. | Mettez Node.js à jour. | [doctor](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-doctor/#checks) |
| doctor : `pack.unknown` / `pack.core-missing` | Le manifeste nomme un pack inconnu ou n’a pas Core. | Restaurez le manifeste, ou réinstallez avec la version qui l’a créé. | [doctor](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-doctor/#checks) |
| doctor : `file.modified` ou `adapter.modified` (avertissement) | Vous avez modifié un fichier géré ou d’instructions. | Normal. `update` le gardera ; comparez à la main quand vous voulez le nouveau contenu. | [update](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-update/#what-changes) |
| doctor : `adapter.unowned` ou `adapter.adopted` | Le fichier d’instructions n’est pas à BMAD+, ou un outil du dépôt l’a généré. | Fusionnez à la main, ou déplacez-le et relancez `install` pour cet outil. | [adapters](https://bmad-plus.rochetta.fr/fr/docs/reference/adapters/) |
| doctor : `runtime.python-unverified` (avertissement) | L’environnement d’un pack Python n’a pas été sondé. | `doctor --verify-python` pour le sonder ; `install --provision-python` pour le créer. | [doctor](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-doctor/) |
| L’assistant semble suivre d’anciennes instructions BMAD+ après une mise à jour | L’outil a chargé son fichier d’instructions avant la mise à jour. | Rechargez les instructions ou ouvrez une nouvelle session (la commande l’indique). Regardez les états `adapter.*` de `doctor` : un fichier préservé n’a pas été rafraîchi. | [update](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-update/) |
| Un agent est inconnu de l’assistant | Le fichier d’instructions de l’outil n’a pas été écrit ou pas lu (pour Aider, pas ajouté à sa configuration). | Vérifiez `--tools` ; pour Aider, ajoutez `read: CONVENTIONS.md` à `.aider.conf.yml`. | [adapters](https://bmad-plus.rochetta.fr/fr/docs/reference/adapters/) |
| Après la désinstallation, des fichiers restent | Ils étaient modifiés ou ne sont pas à BMAD+ ; mémoire et configuration sont gardées exprès. | Supprimez-les vous-même si vous voulez qu’ils disparaissent. | [uninstall](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-uninstall/#reads-writes) |

<a id="orchestration"></a>
## Intake, essaim, Nexus, acceptation, revue

**Gates et refus qui ne sont pas des bogues**

| Symptôme | Cause | Solution | Détails |
| --- | --- | --- | --- |
| `swarm init` affiche `needs approval` et sort avec 2 ; aucun brief écrit | L’exécution demande plus de sous-agents que `swarm.budget` (26 par défaut). | Demandez à une personne. Après un oui, relancez avec `--approved --seed <seed>` comme indiqué. Ou baissez `--n`. | [swarm](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-swarm/#errors) |
| `swarm save` affiche `Swarm: Reply of unit U refused: ...` | La réponse ne respecte pas le contrat de réponse ; rien n’a été écrit. | Redemandez à ce sous-agent, ou laissez l’unité manquante. N’écrivez jamais la réponse vous-même. | [swarm](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-swarm/#errors) |
| `swarm tally` dit `1 of 30 units counted; 29 skipped` | Seules les réponses valides sont comptées ; les unités manquantes ou invalides sont écartées et nommées. | Lancez `check`, puis `briefs`, et redemandez une fois aux unités ouvertes. | [swarm](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-swarm/) |
| `intake plan` sort avec 2 et `not ready`, `Must-haves still open: ...` | Au moins une question indispensable n’a pas de réponse. | Posez les questions listées, `record` les réponses, replanifiez. | [intake](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-intake/#errors) |
| `Intake: <answers> does not answer this intake: ...` | Le questionnaire a changé après l’enregistrement de réponses. | Lancez `record --reset`, puis reposez les questions. | [intake](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-intake/#errors) |
| `studio prepare` affiche `needs-input` et sort avec 2 | Le workflow a besoin d’une demande ou d’un fichier d’entrée. | Ajoutez `--request` ou `--input`. | [studio](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-studio/) |
| `Dev Studio: Dev Studio is not installed. Run bmad-plus install --packs core,dev-studio` | Le pack n’est pas dans ce projet. | Installez le pack. | [studio](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-studio/) |
| `nexus` : `Another mutation owns writer.lock; inspect before explicit recovery.` | Une autre commande Nexus tourne, ou l’une a été tuée. | Attendez ; si elle a été tuée, `inspect`, puis `recover-lock`. | [nexus](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-nexus/) |
| `nexus verify` sort avec 1 ; `Stale evidence: checked artifacts or write scope changed.` | Des fichiers ont changé après la vérification. | Relancez `verify` avant `accept`. | [nexus](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-nexus/) |
| `uat gate` sort avec 2 (`awaiting`), ou `uat read` affiche `<id>: no run yet` | Aucune exécution terminée n’existe pour cette recette. | Jouez la page de recette jusqu’au bout et importez ou servez les résultats. | [uat](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-uat/) |
| `uat gate` sort avec 3 (`stale`) | La dernière exécution répond à une autre révision de la recette. | Rejouez la recette après le changement. | [uat](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-uat/) |
| `review gate` sort avec 2 (`incomplete`) | La couverture ou les constats manquent, ou la revue s’est arrêtée tôt. | Terminez avec `review continue` ; ne mettez `run.stop` à `completed` que si c’est vrai. | [review](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-review/) |
| `review continue` sort avec 3 (`moved`) | Le code ou les règles ont changé depuis le scellement du périmètre. | Scellez un nouveau périmètre, puis `review compare <new> --since <old>`. | [review](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-review/) |
| `assurance: BMAD_PLUS_ASSURANCE_KEY must hold at least 32 characters` | La clé de signature est trop courte. | Utilisez une clé de 32 caractères ou plus, ou supprimez-la. | [assurance](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-assurance/) |
| `assurance verify` sort avec 1 | Le dossier n’est pas étayé : arbre sale, contrôle périmé, en échec ou manquant, ou, si vous avez passé `--ledger-head`, un registre qui ne contient plus cet enregistrement. | Lancez les contrôles manquants, validez, et revérifiez. | [assurance](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-assurance/) |

<a id="memory"></a>
## Mémoire

**Symptômes de la mémoire**

| Symptôme | Cause | Solution | Détails |
| --- | --- | --- | --- |
| `memory status` affiche `Not installed. Run: npx bmad-plus install (select Memory pack)` | Le projet n’a pas de `.agents/memory/`. | Installez le pack Memory. | [memory](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-memory/) |
| `memory export` affiche `Global brain not found. Nothing to export.` | Pas de cerveau global dans `~/.bmad-plus/brain`. | Installez le pack Memory dans n’importe quel projet pour le créer. | [memory](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-memory/) |
| `mem recall` échoue : `Evidence ranking supports project-local lexical recall only.` | `--ranking evidence` avec `--scope portfolio`. | Utilisez la portée projet. | [mem](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-mem/) |
| `mem observe` échoue : `Outcome source is not an accepted task with current independently verified evidence.` | La tâche Nexus n’est ni vérifiée ni acceptée. | Lancez d’abord `nexus verify` et `nexus accept`. | [mem](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-mem/) |
| `Memory writer lock is occupied. ...` | Une autre écriture `mem` tourne ou a été tuée. | Attendez ; supprimez `.bmad/memory/writer.lock` seulement si aucun processus `mem` ne tourne. | [mem](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-mem/) |

> **Astuce · Toujours bloqué** Lancez `doctor --json` et gardez sa sortie avec le message exact et le code de sortie. Ces trois éléments sont ce que toute personne qui vous aide demandera en premier.

**Voir aussi**

- [Codes de sortie de chaque commande](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-overview/#exit-codes)
- [doctor](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-doctor/)
- [Tout le cycle de vie](https://bmad-plus.rochetta.fr/fr/docs/guides/install-lifecycle/)
- [Arborescence du projet](https://bmad-plus.rochetta.fr/fr/docs/reference/project-layout/)

[Documentation BMAD+](https://bmad-plus.rochetta.fr/fr/docs/) · [Questions et dépannage](https://bmad-plus.rochetta.fr/fr/docs/faq/)

[Code sur GitHub](https://github.com/lrochetta/BMAD-PLUS)