SpyBara
Go Premium

plugins/mods/troubleshoot.md 2026-10-01 23:59 UTC to 2026-10-02 19:58 UTC

This page contains 81 additions and 79 deletions.

2026
Thu 1 23:59 Fri 2 19:58

Solucionar problemas de un mod

Descubre por qué un mod de Claude Code no hace nada: relaciona el síntoma o mensaje con su causa, consulta los mensajes de rechazo y lee el registro de depuración.

Cuando el módulo de un mod o uno de sus hooks falla, Claude Code lo omite y la sesión continúa, por lo que un mod defectuoso puede parecer uno que no hace nada. Empieza por comprobar qué leyó Claude Code de tu mod y dónde informa de un problema; luego busca el síntoma o mensaje que tienes.

Averigua por qué un mod no hace nada

Cuando un mod no hace nada, revisa lo que Claude Code lee de los archivos del mod y la línea que escribe cuando omite algo. Para lo primero, en tu shell ejecuta claude plugin validate con el directorio del mod, como en claude plugin validate ./first-mod. Detecta un evento mal escrito, un manifiesto incorrecto y un módulo que Claude Code no puede leer, sin iniciar una sesión.

Cuando un módulo no se carga, se omite un hook u otro mod rechaza el tuyo, Claude Code escribe una línea que nombra tu mod. Dónde lees esa línea depende de la sesión:

  • Una sesión que recarga en caliente un directorio de plugin: una línea atenuada en la transcripción. Es una sesión interactiva que iniciaste con --plugin-dir, o una en la que habilitaste la recarga en caliente para los mods que escribió Claude.
  • Cualquier otra sesión interactiva, como una que ejecuta un mod que instalaste desde un marketplace: solo el registro de depuración. Para obtenerlo, inicia la sesión con claude --debug.
  • Una ejecución de claude -p con --plugin-dir: stderr, en el formato de salida de texto predeterminado. Un rechazo por parte de otro mod va solo al registro de depuración.

Comprobar si los mods pueden cargarse

Para comprobar si tu configuración permite que los mods se carguen, sin instalar ninguno, ejecuta claude plugin test en tu shell, desde un directorio que no contenga un mod. No necesitas una sesión. El mensaje que imprime te indica el estado:

El mensaje incluye Qué significa
no hooks module to load Los mods pueden cargarse. El comando no encontró ningún mod para probar en este directorio.
hooks modules are turned off here Un ajuste está bloqueando tus mods: disableAllHooks en tu propia configuración, o la política de tu organización
hooks modules are turned off in this process Anthropic ha desactivado de forma remota los mods instalados. Ningún ajuste en tu máquina los vuelve a activar.

Una organización también puede establecer allowManagedModsOnly para permitir solo sus propios mods, algo que este comando no informa. En ese caso, un mod que instales no se carga, y un mensaje indica el motivo.

El mod no se carga

No aparece nada de lo que agrega el mod: ningún comando, ningún dibujo y ningún cambio de comportamiento.

Tu versión es anterior a 2.1.287

claude --version muestra una versión anterior a 2.1.287. Tu versión es anterior a que los mods estuvieran activados de forma predeterminada.

Actualiza Claude Code.

La línea `mods active` no nombra el mod

No aparece nada de lo que agrega el mod, y la línea mods active en /plugin no lo nombra. El módulo de hooks no se cargó. Cuando Claude Code lo rechazó, el registro de depuración tiene una línea que empieza con hooks module, el nombre del mod y not loaded:, como en hooks module first-mod@inline not loaded: disableAllHooks in managed settings para un mod cargado con --plugin-dir.

Lee el motivo que aparece después de los dos puntos. La sección mensajes de rechazo enumera cada uno. Si el registro no tiene una línea así, revisa las demás entradas de este grupo.

Algunos ajustes detienen un mod y dejan funcionando el resto de su plugin. Activar o desactivar mods los nombra.

Una ejecución de `claude -p` muestra `hooks module not loaded`

La línea empieza con el nombre del mod y va a stderr. El módulo de hooks fue rechazado. Una ejecución no interactiva no tiene transcripción, así que el mensaje va a stderr.

Lee el motivo que aparece después de los dos puntos. La sección mensajes de rechazo enumera cada uno.

Mensajes de rechazo

Cada uno de estos aparece después de hooks module, el nombre del mod y not loaded: en el registro de depuración.

El mensaje empieza con Qué significa
hooks modules are turned off for installed plugins in this process Anthropic desactivó de forma remota los mods instalados. Ningún ajuste en tu máquina los vuelve a activar.
disableAllHooks in managed settings Tu organización desactivó los hooks de los plugins instalados
only managed plugins and built-in plugins run allowManagedHooksOnly está establecido, o disableAllHooks está establecido en un archivo de configuración distinto de la configuración administrada
installed plugins that are not managed load no hooks module in this mode (--bare) Iniciaste Claude Code con --bare
another plugin of that name loads first Dos plugins comparten un nombre. Se usa el administrado, o el que se cargó primero.

Mensajes de la protección integrada

En una máquina con configuración administrada, o para un usuario que inició sesión con un plan Team o Enterprise, la protección integrada puede rechazar un mod o una de sus respuestas. Cada mensaje nombra la opción que el administrador de tu organización establece para cambiar la regla.

El mensaje contiene Qué significa Dónde aparece
mods are limited to your organization's by policy (allowManagedModsOnly) Tu organización solo permite sus propios mods, así que el tuyo no se cargó El registro de depuración, y la transcripción en una sesión que recarga en caliente un directorio de plugin
tried to lift a deny rule in your settings El hook tool.check de tu mod aprobó una llamada que una regla deny rechaza. La llamada sigue denegada. La transcripción y el registro de depuración, una vez por cada mod en una sesión. En una ejecución de claude -p, solo el registro de depuración.
the deny rules in your settings could not be checked for this call, so it is refused La protección falló al verificar una llamada que un mod aprobó, así que rechazó la llamada El motivo que Claude lee para la llamada denegada

`validate` pasa y no muestra ninguna línea `hooks`

hooks/hooks.json no tiene una clave modules, o la clave está mal escrita.

Agrega "modules": ["./register.js"].

`hooks module did not load`

La línea empieza con el nombre del mod, luego hooks module did not load: y un motivo, que indica el archivo y la línea cuando el problema está en tu código. Claude Code no pudo cargar el módulo, por ejemplo porque su código de nivel superior lanzó una excepción.

Corrige el error que indica el motivo.

`options do not fit plugin.json userConfig`

La línea empieza con el nombre del mod, luego hooks module did not load: options do not fit plugin.json userConfig: y un motivo. Una opción no pasa la validación contra su campo userConfig, como un número por encima del max del campo, o un campo obligatorio no tiene valor.

Establece o cambia el valor. El final de la línea nombra su entrada pluginConfigs en settings.json.

Ningún mod se carga en un directorio que abriste por primera vez

No respondiste la solicitud de confianza del directorio.

Inicia una sesión interactiva en ese directorio con claude y acepta la solicitud de confianza con la que se abre.

No se carga ningún plugin instalado

Iniciaste Claude Code con --safe-mode.

Inicia sin el flag.

Un hook se omite o un mod se descarga

El mod se cargó y luego Claude Code omitió uno de sus hooks o lo descargó.

`hook skipped`

La línea nombra el mod y el evento, luego dice hook skipped: y un motivo, como en first-mod: tool.call hook skipped: threw Error: boom. Un hook lanzó una excepción, superó su límite de tiempo o devolvió un resultado con una forma incorrecta. La línea aparece una vez por cada evento y tipo de fallo hasta que el mod se recarga.

Corrige el error. El registro de depuración tiene una línea por cada ocurrencia.

`no command.run hook answered it`

Ejecutas un comando que agregó tu mod y la respuesta nombra el mod y el comando, como en first-mod registered /tally but no command.run hook answered it, y luego te indica que agregues un hook. Claude Code imprime esa respuesta cuando el comando llega al final de la cadena sin respuesta, lo cual ocurre en dos casos:

  • Ningún hook respondió al comando: el módulo no tiene un hook command.run, el filtro del hook nombra un comando diferente, o el hook devolvió next(e)
  • Claude Code omitió el hook: hook skipped enumera los motivos. Pasar focus: false a $.ui.open es una forma de llegar a esto.

Si el módulo ya tiene el hook que describe la respuesta, busca una línea hook skipped que nombre command.run, la cual indica el motivo. Una prueba que ejecuta el comando falla con el mismo motivo.

`it crashed the hooks worker`

La línea comienza con el nombre del mod, como en first-mod was unloaded: it crashed the hooks worker. Los mods instalados comparten un único hilo worker. El worker dejó de responder o falló, y Claude Code lo atribuyó a este mod y lo descargó. Un hook que bloquea el hilo, como un bucle que nunca usa await, es una de las causas.

Corrige el hook.

`mods that run in the hooks worker are off for this session`

La línea dice hooks: mods that run in the hooks worker are off for this session: it crashed 3 times. El worker se detuvo tres veces y Claude Code no pudo atribuir las detenciones a un solo mod, así que descargó todos los mods que no son integrados, incluidos los mods que instala tu organización. Esta línea llega a la transcripción en cada sesión interactiva.

Ejecuta /reload-plugins para cargarlos de nuevo.

Se deniega una llamada a herramienta

El mod se cargó y sus hooks se ejecutan, y una llamada a herramienta que tocó es rechazada.

`a hook changed this call's input after the model wrote it`

En modo automático, una llamada a herramienta denegada da este motivo. Un hook cambió la entrada de la llamada a herramienta después de que el clasificador del lado del servidor la revisara, por lo que esa revisión no cubre lo que se ejecutaría. El hook puede ser un hook tool.call o turn.step de un mod, o un hook de configuración PreToolUse. El mensaje no dice cuál.

El mensaje le indica a Claude que emita la llamada una vez más tal como quedó registrada. Si también se deniega, el hook cambia la entrada cada vez, así que desactiva el mod o el hook, o sal del modo automático y aprueba la llamada tú mismo.

Un mensaje sobre las reglas de denegación en tu configuración

tried to lift a deny rule in your settings y the deny rules in your settings could not be checked for this call, so it is refused provienen ambos de la protección integrada.

Búscalos en Mensajes de la protección integrada.

Un dibujo no aparece o no responde

El mod se cargó, y su panel, banda o controles no se comportan como esperas.

Un panel o una banda está vacío o muestra el contenido habitual de Claude Code

El árbol que devolvió tu hook no pasó la validación. Con --plugin-dir, la transcripción dice ui.render (Pane) refused: con el motivo, como en first-mod: ui.render (Pane) refused: Box prop "flexDirection" must be one of row, column, row-reverse, column-reverse; the engine drew its own. El registro de depuración tiene a hook returned a tree that does not validate con el mismo motivo.

Lee el motivo en esa línea. Las causas comunes son una prop que el elemento no acepta y un elemento que la app no tiene.

`$.ui.open` se ejecuta y no aparece ningún panel

La llamada no provino de algo que hizo el usuario, y la terminal es más estrecha que el ancho que necesita ese panel.

Abre el panel desde un comando o un botón, o revisa el resultado isPlaced de la llamada. Consulta Abrir un panel en el momento adecuado.

Los atajos de teclado no hacen nada

Tu panel no tiene el foco del teclado.

Presiona Ctrl+X y luego Tab, o haz clic en el panel. Ábrelo con focus: true desde un comando.

Un dibujo funciona en la terminal y no en la app de escritorio

El punto de renderizado o el elemento no está disponible allí.

Consulta las tablas de puntos de renderizado y elementos.

Se pierde una edición o un valor

El mod se ejecuta, y un cambio que hiciste o un valor que conservaba no está.

Tus ediciones no surten efecto

Estás editando un plugin que instalaste. Claude Code ejecuta la copia en caché de la versión instalada.

Desarrolla con --plugin-dir apuntando a tu copia de trabajo, como en claude --plugin-dir ./first-mod, que se recarga cuando guardas.

Un valor se restablece cuando el módulo se recarga

Las variables a nivel de módulo se reinicializan en cada recarga.

Guarda el valor en $.state o $.store.

Un valor se restablece después de `/clear`, `/resume` o `/branch`

Un valor se restablece, o un valor guardado se reemplaza por su valor predeterminado. Cada uno de esos comandos restablece $.state a sus valores predeterminados, y session.start no se vuelve a disparar.

Carga de nuevo el valor guardado en un hook classic.SessionStart.

Lee el registro de depuración

El registro de depuración tiene una línea por cada módulo que Claude Code carga o rechaza, cada hook que falla y cada resultado que rechaza, así que es donde debes buscar cuando la transcripción no muestra nada. Para generar uno, en tu shell inicia Claude Code con --debug, o con --debug-file <path> para elegir dónde se guarda:

claude --debug-file ./mod-debug.log --plugin-dir ./first-mod

En otra terminal, sigue el archivo y filtra por el nombre de tu mod:

tail -f ./mod-debug.log | grep first-mod

Un mod que se cargó tiene una línea que lo nombra y enumera los eventos que maneja. Un mod cargado con --plugin-dir aparece con su nombre seguido de @inline:

hooks module first-mod@inline loaded (worker, environment 2, tier user); events: session.start,tool.call,command.run,ui.render

Un dibujo que no pasó la validación cuenta como un resultado rechazado y también recibe una línea. Para escribir tus propias líneas en el registro, llama a $.ui.log con un segundo argumento, como en $.ui.log('message', { to: 'debug' }). Sin el segundo argumento, $.ui.log agrega una línea atenuada a la transcripción.

Mientras editas un mod cargado con --plugin-dir, la transcripción muestra una línea por cada recarga que nombra el mod y enumera sus hooks. Si un guardado rompe el módulo, la línea dice reload failed, the previous version stays loaded: con el motivo, y la última versión que funcionaba sigue ejecutándose.

Próximos pasos