Parcourir la documentation
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.
Sur cette page
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.
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
npx --no-install bmad-plus --version
npx --no-install bmad-plus doctor
npx --no-install bmad-plus update-check --offlineLa 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.
Installer et mettre à 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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
...; 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 |
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 |
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 |
Erreurs de doctor et instructions périmées
| 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 |
doctor : erreur runtime.node | Node.js est sous la version 20.0.0. | Mettez Node.js à jour. | doctor |
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 |
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 |
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 |
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 |
| 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 |
| 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 |
| 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 |
Intake, essaim, Nexus, acceptation, revue
| 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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
mem recall échoue : Evidence ranking supports project-local lexical recall only. | --ranking evidence avec --scope portfolio. | Utilisez la portée projet. | 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 |
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 |
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 La ligne de commande, vue d’ensemble
- doctor doctor
- Tout le cycle de vie Installer, mettre à jour, désinstaller
- Arborescence du projet Arborescence du projet