> ## 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 um mod > Descubra por que um mod Claude Code não faz nada: corresponda o sintoma ou mensagem à sua causa, procure mensagens de recusa e leia o log de depuração. Quando um módulo de um mod ou um de seus hooks falha, Claude Code o ignora e a sessão continua, então um mod quebrado pode parecer um que não faz nada. Comece verificando o que Claude Code leu do seu mod e onde ele relata um problema, depois encontre o sintoma ou mensagem que você tem.

Descubra por que um mod não faz nada

Quando um mod não faz nada, duas verificações encontram o motivo: o que Claude Code lê dos arquivos do mod e a linha que ele escreve quando ignora algo. Para a primeira, em seu shell execute [`claude plugin validate`](/docs/pt/plugins/mods/create#check-what-claude-code-reads-from-your-mod) com o diretório do mod, como em `claude plugin validate ./first-mod`. Isso detecta um evento digitado incorretamente, um manifesto ruim e um módulo que Claude Code não consegue ler, sem iniciar uma sessão. Quando um módulo não carrega, um hook é ignorado ou outro mod recusa o seu, Claude Code escreve uma linha que nomeia seu mod. Onde você lê essa linha depende da sessão: * **Uma sessão que recarrega dinamicamente um diretório de plugin**: uma linha fraca na transcrição. Essa é uma sessão interativa que você iniciou com `--plugin-dir`, ou uma onde você [habilitou o recarregamento dinâmico](/docs/pt/plugins/mods/create#ask-claude-for-a-mod) para mods que Claude escreveu. * **Qualquer outra sessão interativa, como uma que executa um mod que você instalou de um marketplace**: o [log de depuração](#read-the-debug-log) apenas. Para obter um, inicie a sessão com `claude --debug`. * **Uma execução `claude -p` com `--plugin-dir`**: stderr, no formato de saída de texto padrão. Uma recusa por outro mod vai apenas para o log de depuração.

Verifique se os mods podem carregar

Para verificar se sua configuração permite que os mods carreguem, sem instalar um, execute `claude plugin test` em seu shell, a partir de um diretório que não contenha um mod. Você não precisa de uma sessão. A mensagem que ele imprime informa o estado: | A mensagem inclui | O que significa | | :- | :- | | `no hooks module to load` | Os mods podem carregar. O comando não encontrou nenhum mod para testar neste diretório. | | `hooks modules are turned off here` | Uma configuração está mantendo seus mods fora: `disableAllHooks` em suas próprias configurações, ou a política de sua organização | | `hooks modules are turned off in this process` | A Anthropic desativou os mods instalados remotamente. Nenhuma configuração em sua máquina os ativa novamente. | Uma organização também pode definir `allowManagedModsOnly` para permitir apenas seus próprios mods, o que este comando não relata. Nesse caso, um mod que você instala não carrega, e [uma mensagem diz por quê](/docs/pt/plugins/mods/troubleshoot#messages-from-the-built-in-guard).

O mod não carrega

Nada que o mod adiciona aparece: nenhum comando, nenhum desenho e nenhuma mudança de comportamento.

Sua versão é mais antiga que 2.1.287

`claude --version` imprime uma versão mais antiga que 2.1.287. Sua versão é anterior aos mods estarem ativados por padrão. [Atualize Claude Code](/docs/pt/setup#update-claude-code).

A linha `mods active` não nomeia o mod

Nada que o mod adiciona aparece, e a [linha `mods active`](/docs/pt/plugins/mods/overview#see-which-mods-a-session-loaded) em `/plugin` não o nomeia. O módulo hooks não carregou. Quando Claude Code o recusou, o log de depuração tem uma linha que começa com `hooks module`, o nome do mod e `not loaded:`, como em `hooks module first-mod@inline not loaded: disableAllHooks in managed settings` para um mod carregado com `--plugin-dir`. Leia o motivo após os dois pontos. A seção [mensagens de recusa](#refusal-messages) lista cada uma. Se o log não tiver tal linha, trabalhe através das outras entradas neste grupo.

Uma execução `claude -p` imprime `hooks module not loaded`

A linha começa com o nome do mod e vai para stderr. O módulo hooks foi recusado. Uma execução não interativa não tem transcrição, então a mensagem vai para stderr. Leia o motivo após os dois pontos. A seção [mensagens de recusa](#refusal-messages) lista cada uma.

Mensagens de recusa

Cada uma delas segue `hooks module`, o nome do mod e `not loaded:` no log de depuração. | A mensagem começa com | O que significa | | :- | :- | | `hooks modules are turned off for installed plugins in this process` | A Anthropic desativou os mods instalados remotamente. Nenhuma configuração em sua máquina os ativa novamente. | | `disableAllHooks in managed settings` | Sua organização desativou hooks de plugins instalados | | `only managed plugins and built-in plugins run` | `allowManagedHooksOnly` está definido, ou `disableAllHooks` está definido em um arquivo de configurações diferente de configurações gerenciadas | | `installed plugins that are not managed load no hooks module in this mode (--bare)` | Você iniciou Claude Code com `--bare` | | `another plugin of that name loads first` | Dois plugins compartilham um nome. O gerenciado, ou o carregado primeiro, é usado. |

Mensagens do guarda integrado

Em uma máquina com configurações gerenciadas, ou para um usuário conectado com um plano Team ou Enterprise, o [guarda integrado](/docs/pt/plugins/mods/admin#know-what-happens-by-default) pode recusar um mod ou uma de suas respostas. Cada mensagem nomeia a opção que o administrador de sua organização define para alterar a regra. | A mensagem contém | O que significa | Onde aparece | | :- | :- | :- | | `mods are limited to your organization's by policy (allowManagedModsOnly)` | Sua organização permite apenas [seus próprios mods](/docs/pt/plugins/mods/admin#install-your-organizations-mods), então o seu não foi carregado | O log de depuração e a transcrição em uma [sessão que recarrega dinamicamente um diretório de plugin](#find-out-why-a-mod-does-nothing) | | `tried to lift a deny rule in your settings` | O hook [`tool.check`](/docs/pt/plugins/mods/reference#tools) do seu mod aprovou uma chamada que uma regra `deny` recusa. A chamada permanece recusada. | A transcrição e o log de depuração, uma vez para cada mod em uma sessão. Em uma execução `claude -p`, apenas o log de depuração. | | `the deny rules in your settings could not be checked for this call, so it is refused` | O guarda falhou ao verificar uma chamada que um mod aprovou, então recusou a chamada | O motivo que Claude lê para a chamada recusada |

`validate` passa e não lista nenhuma linha `hooks`

`hooks/hooks.json` não tem uma chave `modules`, ou a chave está digitada incorretamente. Adicione `"modules": ["./register.js"]`.

`hooks module did not load`

A linha começa com o nome do mod, depois `hooks module did not load:` e um motivo, que fornece o arquivo e a linha quando o problema está em seu código. Claude Code não conseguiu carregar o módulo, por exemplo porque seu código de nível superior lançou. Corrija o erro que o motivo nomeia.

`options do not fit plugin.json userConfig`

A linha começa com o nome do mod, depois `hooks module did not load: options do not fit plugin.json userConfig:` e um motivo. Uma opção não se encaixa em seu campo [`userConfig`](/docs/pt/plugins/components#user-configuration), como um número acima do `max` do campo, ou um campo obrigatório não tem valor. Defina ou altere o valor. O final da linha nomeia sua entrada `pluginConfigs` em `settings.json`.

Nenhum mod carrega em um diretório que você abriu pela primeira vez

Você não respondeu ao prompt de confiança para o diretório. Inicie uma sessão interativa nesse diretório com `claude` e aceite o prompt de confiança que ele abre.

Nenhum plugin instalado carrega

Você iniciou Claude Code com `--safe-mode`. Inicie sem a flag.

Um hook é ignorado ou um mod é descarregado

O mod carregou e então Claude Code ignorou um de seus hooks ou o descarregou.

`hook skipped`

A linha nomeia o mod e o evento, depois diz `hook skipped:` e um motivo, como em `first-mod: tool.call hook skipped: threw Error: boom`. Um hook lançou, executou além de seu [limite de tempo de 10 segundos](/docs/pt/plugins/mods/reference#limits), ou retornou um resultado de forma incorreta. A linha aparece uma vez para cada evento e tipo de falha até o mod recarregar. Corrija o erro. O log de depuração tem uma linha para cada ocorrência.

`it crashed the hooks worker`

A linha começa com o nome do mod, como em `first-mod was unloaded: it crashed the hooks worker`. Os mods instalados compartilham um thread de worker. O worker parou de responder ou travou, e Claude Code rastreou isso para este mod e o descarregou. Um hook que bloqueia a thread, como um loop que nunca aguarda, é uma causa. Corrija o hook.

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

A linha lê `hooks: mods that run in the hooks worker are off for this session: it crashed 3 times`. O worker parou três vezes e Claude Code não conseguiu rastrear as paradas para um mod, então descarregou cada mod que não é integrado, incluindo mods que sua organização instala. Esta linha chega à transcrição em cada sessão interativa. Execute `/reload-plugins` para carregá-los novamente.

Uma chamada de ferramenta é recusada

O mod carregou e seus hooks executam, e uma chamada de ferramenta que ele tocou é recusada.

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

Em modo automático, uma chamada de ferramenta recusada fornece este motivo. Um hook alterou a entrada da chamada de ferramenta após o [classificador do lado do servidor](/docs/pt/permission-modes#server-side-classifier-review) revisá-la, então essa revisão não cobre o que seria executado. O hook pode ser um [`tool.call`](/docs/pt/plugins/mods/reference#tools) ou [`turn.step`](/docs/pt/plugins/mods/reference#turns) hook do mod, ou um hook de configurações [`PreToolUse`](/docs/pt/hooks#pretooluse). A mensagem não diz qual. A mensagem diz a Claude para emitir a chamada novamente conforme registrado. Se isso também for recusado, o hook altera a entrada toda vez, então desative o mod ou hook, ou saia do modo automático e aprove a chamada você mesmo.

Uma mensagem sobre as regras de negação em suas configurações

`tried to lift a deny rule in your settings` e `the deny rules in your settings could not be checked for this call, so it is refused` ambas vêm do guarda integrado. Procure-as em [Mensagens do guarda integrado](#messages-from-the-built-in-guard).

Um desenho não aparece ou responde

O mod carregou e seu painel, banda ou controles não se comportam como você espera.

Um painel ou banda está vazio ou mostra o conteúdo usual de Claude Code

A [árvore](/docs/pt/plugins/mods/interface#build-a-tree-from-elements) que seu hook retornou não validou. Com `--plugin-dir`, a transcrição diz `ui.render (Pane) refused:` com o motivo, como em `first-mod: ui.render (Pane) refused: Box prop "flexDirection" must be one of row, column, row-reverse, column-reverse; the engine drew its own`. O log de depuração tem `a hook returned a tree that does not validate` com o mesmo motivo. Leia o motivo nessa linha. As causas comuns são uma prop que o elemento não aceita e um elemento que o aplicativo não tem.

`$.ui.open` executa e nenhum painel aparece

A chamada não veio de algo que o usuário fez, e o terminal é mais estreito que 144 colunas. Abra o painel a partir de um comando ou botão, ou verifique o resultado `isPlaced` da chamada. Veja [Abrir um painel no momento certo](/docs/pt/plugins/mods/interface#open-a-pane-at-the-right-time).

Hotkeys não fazem nada

Seu painel não tem foco de teclado. Pressione Ctrl+X depois Tab, ou clique no painel. Abra-o com `focus: true` a partir de um comando.

Um desenho funciona no terminal e não no aplicativo Desktop

O site ou elemento não está disponível lá. Verifique as [render sites](/docs/pt/plugins/mods/reference#render-sites) e tabelas de [elementos](/docs/pt/plugins/mods/reference#elements).

Uma edição ou um valor é perdido

O mod executa e uma mudança que você fez ou um valor que ele manteve não está lá.

Suas edições não entram em vigor

Você está editando um plugin que instalou. Claude Code executa a cópia em cache para a versão instalada. Desenvolva com `--plugin-dir` apontado para sua cópia de trabalho, como em `claude --plugin-dir ./first-mod`, que recarrega quando você salva.

Um valor é redefinido quando o módulo recarrega

Variáveis de nível de módulo são reinicializadas em cada recarregamento. [Mantenha o valor em `$.state` ou `$.store`](/docs/pt/plugins/mods/interface#keep-state).

Um valor é redefinido após `/clear`, `/resume` ou `/branch`

Um valor é redefinido, ou um valor salvo é substituído por seu padrão. Cada um desses comandos redefine `$.state` para seus padrões, e `session.start` não dispara novamente. [Carregue o valor salvo novamente](/docs/pt/plugins/mods/interface#load-a-saved-value-again-after-clear) em um hook `classic.SessionStart`.

Leia o log de depuração

O log de depuração tem uma linha para cada módulo que Claude Code carrega ou recusa, cada hook que falha e cada resultado que recusa, então é onde procurar quando a transcrição não mostra nada. Para escrever um, em seu shell inicie Claude Code com `--debug`, ou com `--debug-file ` para escolher onde ele vai: ```bash theme={null} claude --debug-file ./mod-debug.log --plugin-dir ./first-mod ``` Em outro terminal, siga o arquivo e filtre pelo nome do seu mod: ```bash theme={null} tail -f ./mod-debug.log | grep first-mod ``` Um mod que carregou tem uma linha que o nomeia e lista os eventos que ele conecta. Um mod carregado com `--plugin-dir` aparece sob seu nome seguido por `@inline`: ```text theme={null} hooks module first-mod@inline loaded (worker, environment 2, tier user); events: session.start,tool.call,command.run,ui.render ``` Um desenho que não validou conta como um resultado recusado e também recebe uma linha. Para escrever suas próprias linhas no log, chame [`$.ui.log`](/docs/pt/plugins/mods/api#show-something-without-starting-a-turn) com um segundo argumento, como em `$.ui.log('message', { to: 'debug' })`. Sem o segundo argumento, `$.ui.log` adiciona uma linha fraca à transcrição. Enquanto você edita um mod carregado com `--plugin-dir`, a transcrição mostra uma linha para cada recarregamento que nomeia o mod e lista seus hooks. Se um salvamento quebrar o módulo, a linha diz `reload failed, the previous version stays loaded:` com o motivo, e a última versão de trabalho continua executando.

Próximas etapas

* [Teste um mod](/docs/pt/plugins/mods/test): detecte problemas antes que eles cheguem a uma sessão * [Solucionar problemas de plugins](/docs/pt/plugins/troubleshooting): problemas com instalação e carregamento de um plugin que não são específicos de mods