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

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

Documentación de BMAD+ › [Preguntas y soluciones](https://bmad-plus.rochetta.fr/es/docs/faq/) › Solución de problemas

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.

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

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

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

<a id="install-update"></a>
## Instalar y actualizar

**Fallos de instalación y actualización**

| 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](https://bmad-plus.rochetta.fr/es/docs/reference/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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-install/#errors) |
| 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](https://bmad-plus.rochetta.fr/es/docs/reference/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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-update/#recovery) |
| `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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-doctor/#checks) |
| `Confirm this exact update with --yes.` y luego `Target: vX` | `update --latest` solo informa hasta que apruebes. | Ejecuta `update --latest --yes`. | [update](https://bmad-plus.rochetta.fr/es/docs/reference/cli-update/#two-paths) |
| `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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-update-check/#statuses) |
| 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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-update/#what-changes) |
| `...; 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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-update/#recovery) |
| `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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-install/#re-running) |
| `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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-install/#errors) |

<a id="doctor-and-instructions"></a>
## Errores de doctor e instrucciones obsoletas

**Síntomas de doctor y de los archivos de instrucciones**

| 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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-doctor/#checks) |
| doctor: error `runtime.node` | Node.js es anterior a 20.0.0. | Actualiza Node.js. | [doctor](https://bmad-plus.rochetta.fr/es/docs/reference/cli-doctor/#checks) |
| 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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-doctor/#checks) |
| 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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-update/#what-changes) |
| 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](https://bmad-plus.rochetta.fr/es/docs/reference/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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-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](https://bmad-plus.rochetta.fr/es/docs/reference/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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-uninstall/#reads-writes) |

<a id="orchestration"></a>
## Intake, enjambre, Nexus, aceptación, revisión

**Puertas y rechazos que no son errores**

| 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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-swarm/#errors) |
| `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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-swarm/#errors) |
| `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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-intake/#errors) |
| `Intake: <answers> does not answer this intake: ...` | El cuestionario cambió después de registrar respuestas. | Ejecuta `record --reset` y vuelve a preguntar. | [intake](https://bmad-plus.rochetta.fr/es/docs/reference/cli-intake/#errors) |
| `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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-assurance/) |

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

**Síntomas de la 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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-memory/) |
| `mem recall` falla: `Evidence ranking supports project-local lexical recall only.` | `--ranking evidence` con `--scope portfolio`. | Usa el ámbito de proyecto. | [mem](https://bmad-plus.rochetta.fr/es/docs/reference/cli-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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-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](https://bmad-plus.rochetta.fr/es/docs/reference/cli-overview/#exit-codes)
- [doctor](https://bmad-plus.rochetta.fr/es/docs/reference/cli-doctor/)
- [El ciclo completo](https://bmad-plus.rochetta.fr/es/docs/guides/install-lifecycle/)
- [Estructura del proyecto](https://bmad-plus.rochetta.fr/es/docs/reference/project-layout/)

[Documentación de BMAD+](https://bmad-plus.rochetta.fr/es/docs/) · [Preguntas y soluciones](https://bmad-plus.rochetta.fr/es/docs/faq/)

[Código en GitHub](https://github.com/lrochetta/BMAD-PLUS)