Explorar la documentación
Solución de problemas
Síntoma, causa y solución para los fallos reales de BMAD+: instalaciones y actualizaciones rechazadas, bloqueos obsoletos, errores de doctor, instrucciones obsoletas, enjambres por aprobar.
En esta página
Esta página se organiza por lo que ves, no por comando. Cada fila nombra un fallo que existe en el código, con el mensaje tal como se imprime, la causa y la solución más corta. Los mensajes de la CLI siempre están en inglés, incluso cuando el instalador habla tu idioma; se citan tal cual para que puedas buscarlos. Cuando una fila necesita más, su última columna remite a la página del comando.
Primeros auxilios: tres comandos
De solo lectura; ninguno cambia tu proyecto. Necesitan la copia local del proyecto (npm install --save-dev bmad-plus); sin ella, quita --no-install
npx --no-install bmad-plus --version
npx --no-install bmad-plus doctor
npx --no-install bmad-plus update-check --offlineEl primero imprime la versión del paquete que ejecutas. doctor compara el proyecto con su manifiesto e imprime cada comprobación que no sea un simple acierto; empieza por sus errores. El tercero muestra las versiones instalada y en ejecución sin tocar la red.
Instalar y actualizar
| Síntoma | Causa | Solución | Detalles |
|---|---|---|---|
npx canceled due to missing packages and no YES option | Usaste npx --no-install pero el paquete no está instalado en el proyecto: el instalador no lo añade. | Ejecuta una vez npm install --save-dev bmad-plus, o quita --no-install y usa npx bmad-plus .... | cli-overview |
This command requires a terminal. Run ... (código 1) | El comando necesita respuestas y la entrada no es una terminal (script, CI, tubería). | Añade --yes. | install |
La instalación terminó pero no hay CLAUDE.md, AGENTS.md ni archivo de herramienta. El registro decía No AI tool detected; no instruction adapter written. | --yes nunca adivina una herramienta y no se encontró ninguna carpeta de herramienta. | Vuelve a ejecutar con --tools claude-code (u otros identificadores, o all). | adapters |
BMAD+ vX is installed; this package is vY. Run bmad-plus update first | install solo añade packs y herramientas a la misma versión. | Ejecuta update y luego install de nuevo. | update |
Downgrade refused | El paquete que ejecutas es más antiguo que la versión instalada. | Ejecuta npx bmad-plus@latest .... Para volver atrás, restaura desde un recibo. | update |
Another update is in progress: <path>. o doctor lock.stale | Una instalación o actualización tiene .bmad/update.lock, o murió teniéndolo. | Espera. Si no corre nada y doctor dice «stale», borra el archivo de bloqueo indicado y reintenta. | doctor |
Confirm this exact update with --yes. y luego Target: vX | update --latest solo informa hasta que apruebes. | Ejecuta update --latest --yes. | update |
Update refused: automatic-updates-not-authorized. (update --auto o update --latest --auto) | El modo de la política es notify, así que --auto no está autorizado. | Aprueba a mano con --yes, o elige auto con un rango. | update-policy |
Update refused: fresh-metadata-required | No se pudo llegar a npm para una respuesta fresca. | Revisa la conexión y reintenta; update-check --refresh muestra lo que dice npm. | update-check |
update-check imprime unknown: registry-unavailable o registry-retry-backoff | Sin red, o un fallo anotado hace menos de una hora. | Reintenta con --refresh. No es un fallo: el código de salida es 0. | update-check |
Tras una actualización algunos archivos no cambian y el registro dice preserved (...) | Los editaste, o BMAD+ nunca los registró: se conservan a propósito. | Nada que arreglar. Compara a mano si quieres el contenido nuevo; --restore deshace la actualización. | update |
...; rolled-back. Recovery: bmad-plus update --restore <id> ... | Una escritura falló a medias; la actualización se revirtió sola. | Corrige la causa (disco, permisos, archivo bloqueado) y reintenta. | update |
Install manifest is unreadable or corrupt | El manifiesto está dañado. | install lo guarda como .corrupt.bak y lo reescribe; si no, restaura el archivo. | install |
External module design-skill is X but this BMAD+ expects exactly Y | El pack de habilidades fijado del paquete Design no coincide. | Reinstala el paquete bmad-plus; el proyecto no se tocó. | install |
Errores de doctor e instrucciones obsoletas
| Síntoma | Causa | Solución | Detalles |
|---|---|---|---|
doctor sale con 1 y file.missing: Missing required file: ... | Se borró un archivo que BMAD+ instaló. | Ejecuta install de nuevo; restaura los que faltan y deja los tuyos. | doctor |
doctor: error runtime.node | Node.js es anterior a 20.0.0. | Actualiza Node.js. | doctor |
doctor: pack.unknown / pack.core-missing | El manifiesto nombra un pack desconocido o no tiene Core. | Restaura el manifiesto, o reinstala con la versión que lo creó. | doctor |
doctor: file.modified o adapter.modified (aviso) | Editaste un archivo gestionado o de instrucciones. | Es lo esperado. update lo conservará; compara a mano cuando quieras el contenido nuevo. | update |
doctor: adapter.unowned o adapter.adopted | El archivo de instrucciones no es de BMAD+, o lo generó una herramienta del repositorio. | Fusiona a mano, o apártalo y vuelve a ejecutar install para esa herramienta. | adapters |
doctor: runtime.python-unverified (aviso) | No se sondeó el entorno de un pack de Python. | doctor --verify-python para sondearlo; install --provision-python para crearlo. | doctor |
| El asistente parece seguir instrucciones antiguas de BMAD+ tras una actualización | La herramienta cargó su archivo de instrucciones antes de la actualización. | Recarga las instrucciones o inicia una sesión nueva (el comando lo indica). Mira los estados adapter.* de doctor: un archivo conservado no se refrescó. | update |
| Un agente es desconocido para el asistente | El archivo de instrucciones de la herramienta no se escribió o no se leyó (en Aider, no se añadió a su configuración). | Revisa --tools; en Aider añade read: CONVENTIONS.md a .aider.conf.yml. | adapters |
| Tras desinstalar quedan archivos | Estaban editados o no son de BMAD+; la memoria y la configuración se conservan a propósito. | Bórralos tú si quieres que desaparezcan. | uninstall |
Intake, enjambre, Nexus, aceptación, revisión
| Síntoma | Causa | Solución | Detalles |
|---|---|---|---|
swarm init imprime needs approval y sale con 2; no se escribe ningún brief | La ejecución necesita más subagentes que swarm.budget (26 por defecto). | Pregunta a una persona. Tras un sí, vuelve a ejecutar con --approved --seed <seed> como se imprimió. O baja --n. | swarm |
swarm save imprime Swarm: Reply of unit U refused: ... | La respuesta no cumple el contrato de respuesta; no se escribió nada. | Vuelve a pedírselo a ese subagente, o deja la unidad sin respuesta. Nunca escribas la respuesta tú. | swarm |
swarm tally dice 1 of 30 units counted; 29 skipped | Solo cuentan las respuestas válidas; las unidades ausentes o inválidas se omiten y se nombran. | Ejecuta check, luego briefs, y pide una vez más a las unidades abiertas. | swarm |
intake plan sale con 2 y not ready, Must-haves still open: ... | Al menos una pregunta imprescindible no tiene respuesta. | Haz las preguntas listadas, record las respuestas y planifica de nuevo. | intake |
Intake: <answers> does not answer this intake: ... | El cuestionario cambió después de registrar respuestas. | Ejecuta record --reset y vuelve a preguntar. | intake |
studio prepare imprime needs-input y sale con 2 | El workflow necesita una petición o un archivo de entrada. | Añade --request o --input. | studio |
Dev Studio: Dev Studio is not installed. Run bmad-plus install --packs core,dev-studio | El pack no está en este proyecto. | Instala el pack. | studio |
nexus: Another mutation owns writer.lock; inspect before explicit recovery. | Otro comando de Nexus se está ejecutando, o se mató uno. | Espera; si se mató, inspect y luego recover-lock. | nexus |
nexus verify sale con 1; Stale evidence: checked artifacts or write scope changed. | Los archivos cambiaron tras la verificación. | Vuelve a ejecutar verify antes de accept. | nexus |
uat gate sale con 2 (awaiting), o uat read imprime <id>: no run yet | No existe ninguna ejecución terminada de esta receta. | Recorre la página de la receta hasta el final e importa o sirve los resultados. | uat |
uat gate sale con 3 (stale) | La última ejecución respondió a otra revisión de la receta. | Vuelve a recorrer la receta tras el cambio. | uat |
review gate sale con 2 (incomplete) | Faltan cobertura o hallazgos, o la revisión se detuvo antes de tiempo. | Termina con review continue; pon run.stop en completed solo si de verdad ocurrió. | review |
review continue sale con 3 (moved) | El código o las reglas cambiaron desde que se selló el alcance. | Sella un alcance nuevo y luego review compare <new> --since <old>. | review |
assurance: BMAD_PLUS_ASSURANCE_KEY must hold at least 32 characters | La clave de firma es demasiado corta. | Usa una clave de 32 caracteres o más, o quítala. | assurance |
assurance verify sale con 1 | El caso no está respaldado: árbol sucio, comprobación obsoleta, fallida o ausente, o, si pasaste --ledger-head, un ledger que ya no contiene esa entrada. | Ejecuta las comprobaciones que faltan, haz commit y verifica de nuevo. | assurance |
Memoria
| Síntoma | Causa | Solución | Detalles |
|---|---|---|---|
memory status imprime Not installed. Run: npx bmad-plus install (select Memory pack) | El proyecto no tiene .agents/memory/. | Instala el pack Memory. | memory |
memory export imprime Global brain not found. Nothing to export. | No hay cerebro global en ~/.bmad-plus/brain. | Instala el pack Memory en cualquier proyecto para crearlo. | memory |
mem recall falla: Evidence ranking supports project-local lexical recall only. | --ranking evidence con --scope portfolio. | Usa el ámbito de proyecto. | mem |
mem observe falla: Outcome source is not an accepted task with current independently verified evidence. | La tarea de Nexus no está verificada ni aceptada. | Ejecuta antes nexus verify y nexus accept. | mem |
Memory writer lock is occupied. ... | Otra escritura de mem se está ejecutando o se mató. | Espera; borra .bmad/memory/writer.lock solo si no corre ningún proceso mem. | mem |
Consejo Sigues atascado
Ejecuta doctor --json y guarda su salida junto con el mensaje exacto y el código de salida. Esos tres datos son lo primero que te pedirá quien te ayude.
Véase también
- Códigos de salida de cada comando La línea de comandos, visión general
- doctor doctor
- El ciclo completo Instalar, actualizar, desinstalar
- Estructura del proyecto Estructura del proyecto