> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Solucionar problemas de un mod
> Descubre por qué un mod de Claude Code no hace nada: haz coincidir el síntoma o mensaje con su causa, busca 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 roto puede parecer uno que no hace nada. Comienza verificando qué leyó Claude Code de tu mod y dónde reporta un problema, luego encuentra el síntoma o mensaje que tienes.
Descubre por qué un mod no hace nada
Cuando un mod no hace nada, dos verificaciones encuentran la razón: qué lee Claude Code de los archivos del mod y la línea que escribe cuando omite algo. Para la primera, en tu shell ejecuta [`claude plugin validate`](/docs/es/plugins/mods/create#check-what-claude-code-reads-from-your-mod) 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 o 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 plugins**: una línea tenue en la transcripción. Esa es una sesión interactiva que iniciaste con `--plugin-dir`, o una donde [habilitaste la recarga en caliente](/docs/es/plugins/mods/create#ask-claude-for-a-mod) para mods que Claude escribió.
* **Cualquier otra sesión interactiva, como una que ejecuta un mod que instalaste desde un marketplace**: el [registro de depuración](#read-the-debug-log) solamente. Para obtener uno, inicia la sesión con `claude --debug`.
* **Una ejecución `claude -p` con `--plugin-dir`**: stderr, en el formato de salida de texto predeterminado. Un rechazo por otro mod va al registro de depuración solamente.
Verifica si los mods pueden cargarse
Para verificar si tu configuración permite que los mods se carguen en absoluto, sin instalar uno, 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 dice 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` | Una configuración está manteniendo tus mods fuera: `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 los mods instalados de forma remota. Ninguna configuración en tu máquina los vuelve a activar. |
Una organización también puede establecer `allowManagedModsOnly` para permitir solo sus propios mods, que este comando no reporta. En ese caso, un mod que instales no se carga, y [un mensaje dice por qué](/docs/es/plugins/mods/troubleshoot#messages-from-the-built-in-guard).
El mod no se carga
Nada de lo que agrega el mod aparece: ningún comando, ningún dibujo y ningún cambio de comportamiento.
Tu versión es anterior a 2.1.287
`claude --version` imprime una versión anterior a 2.1.287. Tu versión es anterior a que los mods estén activados de forma predeterminada.
[Actualiza Claude Code](/docs/es/setup#update-claude-code).
La línea `mods active` no nombra el mod
Nada de lo que agrega el mod aparece, y la [línea `mods active`](/docs/es/plugins/mods/overview#see-which-mods-a-session-loaded) en `/plugin` no lo nombra. El módulo hooks no se cargó. Cuando Claude Code lo rechazó, el registro de depuración tiene una línea que comienza 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 la razón después de los dos puntos. La sección [refusal messages](#refusal-messages) enumera cada una. Si el registro no tiene tal línea, trabaja a través de las otras entradas en este grupo.
Una ejecución `claude -p` imprime `hooks module not loaded`
La línea comienza con el nombre del mod y va a stderr. El módulo hooks fue rechazado. Una ejecución no interactiva no tiene transcripción, por lo que el mensaje va a stderr.
Lee la razón después de los dos puntos. La sección [refusal messages](#refusal-messages) enumera cada una.
Mensajes de rechazo
Cada uno de estos sigue a `hooks module`, el nombre del mod y `not loaded:` en el registro de depuración.
| El mensaje comienza con | Qué significa |
| :- | :- |
| `hooks modules are turned off for installed plugins in this process` | Anthropic ha desactivado los mods instalados de forma remota. Ninguna configuración 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 que no sea 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 del guardia integrado
En una máquina con configuración administrada, o para un usuario que inició sesión con un plan de Team o Enterprise, el [guardia integrado](/docs/es/plugins/mods/admin#know-what-happens-by-default) 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 permite solo [sus propios mods](/docs/es/plugins/mods/admin#install-your-organizations-mods), por lo 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 plugins](#find-out-why-a-mod-does-nothing) |
| `tried to lift a deny rule in your settings` | El hook [`tool.check`](/docs/es/plugins/mods/reference#tools) de tu mod aprobó una llamada que una regla `deny` rechaza. La llamada permanece denegada. | La transcripción y el registro de depuración, una vez para cada mod en una sesión. En una ejecución `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` | El guardia falló mientras verificaba una llamada que un mod aprobó, por lo que rechazó la llamada | La razón que Claude lee para la llamada denegada |
`validate` pasa y no enumera 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 comienza con el nombre del mod, luego `hooks module did not load:` y una razón, que proporciona 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 la razón nombra.
`options do not fit plugin.json userConfig`
La línea comienza con el nombre del mod, luego `hooks module did not load: options do not fit plugin.json userConfig:` y una razón. Una opción no se ajusta a su campo [`userConfig`](/docs/es/plugins/components#user-configuration), como un número por encima del `max` del campo, o un campo requerido 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 has respondido al aviso de confianza para el directorio.
Inicia una sesión interactiva en ese directorio con `claude` y acepta el aviso de confianza que abre.
Ningún plugin instalado se carga en absoluto
Iniciaste Claude Code con `--safe-mode`.
Inicia sin la bandera.
Se omite un hook o se descarga un mod
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 una razón, como en `first-mod: tool.call hook skipped: threw Error: boom`. Un hook lanzó una excepción, se ejecutó más allá de su [límite de tiempo de 10 segundos](/docs/es/plugins/mods/reference#limits), o devolvió un resultado de forma incorrecta. La línea aparece una vez para cada evento y tipo de fallo hasta que el mod se recarga.
Corrige el error. El registro de depuración tiene una línea para cada ocurrencia.
`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 hilo de trabajo. El trabajador dejó de responder o se bloqueó, y Claude Code rastreó eso a este mod y lo descargó. Un hook que bloquea el hilo, como un bucle que nunca espera, es una causa.
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 trabajador se detuvo tres veces y Claude Code no pudo rastrear las paradas a un mod, por lo que descargó cada mod que no es integrado, incluidos los mods que tu organización instala. Esta línea llega a la transcripción en cada sesión interactiva.
Ejecuta `/reload-plugins` para cargarlos de nuevo.
El mod se cargó y sus hooks se ejecutan, y se rechaza una llamada de herramienta que tocó.
En modo automático, una llamada de herramienta denegada da esta razón. Un hook cambió la entrada de la llamada de herramienta después de que el [clasificador del lado del servidor](/docs/es/permission-modes#server-side-classifier-review) la revisó, por lo que esa revisión no cubre lo que se ejecutaría. El hook puede ser un hook [`tool.call`](/docs/es/plugins/mods/reference#tools) o [`turn.step`](/docs/es/plugins/mods/reference#turns) de un mod, o un hook de configuración [`PreToolUse`](/docs/es/hooks#pretooluse). El mensaje no dice cuál.
El mensaje le dice a Claude que emita la llamada una vez más como se registró. 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` ambos provienen del guardia integrado.
Búscalos en [Messages from the built-in guard](#messages-from-the-built-in-guard).
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 banda está vacío o muestra el contenido habitual de Claude Code
El [árbol](/docs/es/plugins/mods/interface#build-a-tree-from-elements) que devolvió tu hook no se validó. Con `--plugin-dir`, la transcripción dice `ui.render (Pane) refused:` con la razón, 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 la misma razón.
Lee la razón en esa línea. Las causas comunes son una propiedad que el elemento no toma y un elemento que la aplicación no tiene.
`$.ui.open` se ejecuta y no aparece ningún panel
La llamada no provino de algo que el usuario hizo, y la terminal es más estrecha que 144 columnas.
Abre el panel desde un comando o un botón, o verifica el resultado `isPlaced` de la llamada. Consulta [Open a pane at the right time](/docs/es/plugins/mods/interface#open-a-pane-at-the-right-time).
Las teclas de acceso rápido no hacen nada
Tu panel no tiene el enfoque del teclado.
Presiona Ctrl+X 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 aplicación de escritorio
El sitio o elemento no está disponible allí.
Verifica las [render sites](/docs/es/plugins/mods/reference#render-sites) y las tablas de [elements](/docs/es/plugins/mods/reference#elements).
Se pierde una edición o un valor
El mod se ejecuta y un cambio que hiciste o un valor que mantuvo no está allí.
Tus ediciones no tienen efecto
Estás editando un plugin que instalaste. Claude Code ejecuta la copia en caché para 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 reinicia cuando el módulo se recarga
Las variables a nivel de módulo se reinicializan en cada recarga.
[Mantén el valor en `$.state` o `$.store`](/docs/es/plugins/mods/interface#keep-state).
Un valor se reinicia después de `/clear`, `/resume` o `/branch`
Un valor se reinicia, o un valor guardado se reemplaza por su predeterminado. Cada uno de esos comandos reinicia `$.state` a sus valores predeterminados, y `session.start` no se dispara de nuevo.
[Carga el valor guardado de nuevo](/docs/es/plugins/mods/interface#load-a-saved-value-again-after-clear) en un hook `classic.SessionStart`.
Lee el registro de depuración
El registro de depuración tiene una línea para cada módulo que Claude Code carga o rechaza, cada hook que falla y cada resultado que rechaza, por lo que es donde buscar cuando la transcripción no muestra nada. Para escribir uno, en tu shell inicia Claude Code con `--debug`, o con `--debug-file ` para elegir dónde va:
```bash theme={null}
claude --debug-file ./mod-debug.log --plugin-dir ./first-mod
```
En otra terminal, sigue el archivo y filtra por el nombre de tu mod:
```bash theme={null}
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 engancha. Un mod cargado con `--plugin-dir` aparece bajo su nombre seguido de `@inline`:
```text theme={null}
hooks module first-mod@inline loaded (worker, environment 2, tier user); events: session.start,tool.call,command.run,ui.render
```
Un dibujo que no se validó cuenta como un resultado rechazado y también obtiene una línea. Para escribir tus propias líneas en el registro, llama a [`$.ui.log`](/docs/es/plugins/mods/api#show-something-without-starting-a-turn) con un segundo argumento, como en `$.ui.log('message', { to: 'debug' })`. Sin el segundo argumento, `$.ui.log` agrega una línea tenue a la transcripción.
Mientras editas un mod cargado con `--plugin-dir`, la transcripción muestra una línea para 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 la razón, y la última versión que funcionó sigue ejecutándose.
Próximos pasos
* [Test a mod](/docs/es/plugins/mods/test): detecta problemas antes de que lleguen a una sesión
* [Troubleshoot plugins](/docs/es/plugins/troubleshooting): problemas con la instalación y carga de un plugin que no son específicos de los mods