Risolvere i problemi di un mod
Scopri perché un mod Claude Code non fa nulla: abbina il sintomo o il messaggio alla sua causa, cerca i messaggi di rifiuto e leggi il debug log.
Quando il modulo di un mod o uno dei suoi hooks fallisce, Claude Code lo salta e la sessione continua, quindi un mod rotto può sembrare uno che non fa nulla. Inizia controllando cosa Claude Code ha letto dal tuo mod e dove segnala un problema, quindi trova il sintomo o il messaggio che hai.
Scopri perché un mod non fa nulla
Quando un mod non fa nulla, due controlli trovano il motivo: cosa Claude Code legge dai file del mod e la riga che scrive quando salta qualcosa. Per il primo, nella tua shell esegui claude plugin validate con la directory del mod, come in claude plugin validate ./first-mod. Cattura un evento scritto male, un manifest errato e un modulo che Claude Code non riesce a leggere, senza avviare una sessione.
Quando un modulo non si carica, un hook viene saltato o un altro mod rifiuta il tuo, Claude Code scrive una riga che nomina il tuo mod. Dove leggi quella riga dipende dalla sessione:
- Una sessione che ricarica a caldo una directory di plugin: una riga attenuata nella trascrizione. È una sessione interattiva che hai avviato con
--plugin-dir, oppure una in cui hai abilitato il ricaricamento a caldo per i mod che Claude ha scritto. - Qualsiasi altra sessione interattiva, come una che esegue un mod che hai installato da un marketplace: il debug log solo. Per ottenerne uno, avvia la sessione con
claude --debug. - Un'esecuzione
claude -pcon--plugin-dir: stderr, nel formato di output di testo predefinito. Un rifiuto da parte di un altro mod va al debug log solo.
Controlla se i mod possono caricarsi
Per verificare se la tua configurazione consente ai mod di caricarsi affatto, senza installarne uno, esegui claude plugin test nella tua shell, da una directory che non contiene un mod. Non hai bisogno di una sessione. Il messaggio che stampa ti dice lo stato:
| Il messaggio include | Cosa significa |
|---|---|
no hooks module to load |
I mod possono caricarsi. Il comando non ha trovato alcun mod da testare in questa directory. |
hooks modules are turned off here |
Un'impostazione sta tenendo i tuoi mod fuori: disableAllHooks nelle tue impostazioni, oppure la politica della tua organizzazione |
hooks modules are turned off in this process |
Anthropic ha disattivato i mod installati da remoto. Nessuna impostazione sulla tua macchina li riattiva. |
Un'organizzazione può anche impostare allowManagedModsOnly per consentire solo i suoi mod, che questo comando non segnala. In quel caso un mod che installi non si carica e un messaggio spiega perché.
Il mod non si carica
Nulla di ciò che il mod aggiunge appare: nessun comando, nessun disegno e nessun cambiamento nel comportamento.
La tua versione è più vecchia di 2.1.287
claude --version stampa una versione più vecchia di 2.1.287. La tua versione è precedente ai mod attivi per impostazione predefinita.
La riga `mods active` non nomina il mod
Nulla di ciò che il mod aggiunge appare e la riga mods active in /plugin non lo nomina. Il modulo hooks non si è caricato. Quando Claude Code lo ha rifiutato, il debug log ha una riga che inizia con hooks module, il nome del mod e not loaded:, come in hooks module first-mod@inline not loaded: disableAllHooks in managed settings per un mod caricato con --plugin-dir.
Leggi il motivo dopo i due punti. La sezione refusal messages elenca ognuno. Se il log non ha tale riga, esamina le altre voci in questo gruppo.
Un'esecuzione `claude -p` stampa `hooks module not loaded`
La riga inizia con il nome del mod e va a stderr. Il modulo hooks è stato rifiutato. Un'esecuzione non interattiva non ha trascrizione, quindi il messaggio va a stderr.
Leggi il motivo dopo i due punti. La sezione refusal messages elenca ognuno.
Refusal messages
Ognuno di questi segue hooks module, il nome del mod e not loaded: nel debug log.
| Il messaggio inizia con | Cosa significa |
|---|---|
hooks modules are turned off for installed plugins in this process |
Anthropic ha disattivato i mod installati da remoto. Nessuna impostazione sulla tua macchina li riattiva. |
disableAllHooks in managed settings |
La tua organizzazione ha disattivato gli hooks dai plugin installati |
only managed plugins and built-in plugins run |
allowManagedHooksOnly è impostato, oppure disableAllHooks è impostato in un file di impostazioni diverso dalle impostazioni gestite |
installed plugins that are not managed load no hooks module in this mode (--bare) |
Hai avviato Claude Code con --bare |
another plugin of that name loads first |
Due plugin condividono un nome. Viene utilizzato quello gestito o quello caricato per primo. |
Messages from the built-in guard
Su una macchina con impostazioni gestite, o per un utente connesso con un piano Team o Enterprise, la built-in guard può rifiutare un mod o una delle sue risposte. Ogni messaggio nomina l'opzione che l'amministratore della tua organizzazione imposta per modificare la regola.
| Il messaggio contiene | Cosa significa | Dove appare |
|---|---|---|
mods are limited to your organization's by policy (allowManagedModsOnly) |
La tua organizzazione consente solo i suoi mod, quindi il tuo non è stato caricato | Il debug log e la trascrizione in una sessione che ricarica a caldo una directory di plugin |
tried to lift a deny rule in your settings |
Il tool.check hook del tuo mod ha approvato una chiamata che una regola deny rifiuta. La chiamata rimane negata. |
La trascrizione e il debug log, una volta per ogni mod in una sessione. In un'esecuzione claude -p, il debug log solo. |
the deny rules in your settings could not be checked for this call, so it is refused |
La guard ha fallito durante il controllo di una chiamata che un mod ha approvato, quindi ha rifiutato la chiamata | Il motivo che Claude legge per la chiamata negata |
`validate` passa e non elenca alcuna riga `hooks`
hooks/hooks.json non ha una chiave modules, oppure la chiave è scritta male.
Aggiungi "modules": ["./register.js"].
`hooks module did not load`
La riga inizia con il nome del mod, quindi hooks module did not load: e un motivo, che fornisce il file e la riga quando il problema è nel tuo codice. Claude Code non ha potuto caricare il modulo, ad esempio perché il suo codice di livello superiore ha lanciato un'eccezione.
Correggi l'errore che il motivo nomina.
`options do not fit plugin.json userConfig`
La riga inizia con il nome del mod, quindi hooks module did not load: options do not fit plugin.json userConfig: e un motivo. Un'opzione non si adatta al suo campo userConfig, come un numero superiore al max del campo, oppure un campo obbligatorio non ha valore.
Imposta o modifica il valore. La fine della riga nomina la sua voce pluginConfigs in settings.json.
Nessun mod si carica in una directory che hai aperto per la prima volta
Non hai risposto al prompt di fiducia per la directory.
Avvia una sessione interattiva in quella directory con claude e accetta il prompt di fiducia che apre.
Nessun plugin installato si carica affatto
Hai avviato Claude Code con --safe-mode.
Avvia senza il flag.
Un hook viene saltato o un mod viene scaricato
Il mod si è caricato e poi Claude Code ha saltato uno dei suoi hooks o lo ha scaricato.
`hook skipped`
La riga nomina il mod e l'evento, quindi dice hook skipped: e un motivo, come in first-mod: tool.call hook skipped: threw Error: boom. Un hook ha lanciato un'eccezione, ha superato il suo limite di tempo di 10 secondi, oppure ha restituito un risultato di forma sbagliata. La riga appare una volta per ogni evento e tipo di errore fino al ricaricamento del mod.
Correggi l'errore. Il debug log ha una riga per ogni occorrenza.
`it crashed the hooks worker`
La riga inizia con il nome del mod, come in first-mod was unloaded: it crashed the hooks worker. I mod installati condividono un thread di lavoro. Il worker ha smesso di rispondere o si è bloccato e Claude Code ha tracciato che ciò è dovuto a questo mod e lo ha scaricato. Un hook che blocca il thread, come un ciclo che non attende mai, è una causa.
Correggi l'hook.
`mods that run in the hooks worker are off for this session`
La riga legge hooks: mods that run in the hooks worker are off for this session: it crashed 3 times. Il worker si è fermato tre volte e Claude Code non ha potuto tracciare gli arresti a un mod, quindi ha scaricato ogni mod che non è built-in, inclusi i mod che la tua organizzazione installa. Questa riga raggiunge la trascrizione in ogni sessione interattiva.
Esegui /reload-plugins per caricarli di nuovo.
Una chiamata di strumento viene negata
Il mod si è caricato e i suoi hooks vengono eseguiti e una chiamata di strumento che ha toccato viene rifiutata.
`a hook changed this call's input after the model wrote it`
In modalità auto, una chiamata di strumento negata fornisce questo motivo. Un hook ha modificato l'input della chiamata di strumento dopo che il classificatore lato server lo ha esaminato, quindi quella revisione non copre ciò che verrebbe eseguito. L'hook può essere il tool.call o il turn.step hook del mod, oppure un hook di impostazioni PreToolUse. Il messaggio non dice quale.
Il messaggio dice a Claude di emettere la chiamata ancora una volta come registrata. Se viene negata anche quella, l'hook cambia l'input ogni volta, quindi disattiva il mod o l'hook, oppure esci dalla modalità auto e approva la chiamata tu stesso.
Un messaggio sulle regole di negazione nelle tue impostazioni
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 provengono entrambi dalla built-in guard.
Cercali in Messages from the built-in guard.
Un disegno non appare o non risponde
Il mod si è caricato e il tuo riquadro, banda o controlli non si comportano come ti aspetti.
Un riquadro o una banda è vuoto o mostra il solito contenuto di Claude Code
L'albero che il tuo hook ha restituito non ha convalidato. Con --plugin-dir, la trascrizione dice ui.render (Pane) refused: con il motivo, come in first-mod: ui.render (Pane) refused: Box prop "flexDirection" must be one of row, column, row-reverse, column-reverse; the engine drew its own. Il debug log ha a hook returned a tree that does not validate con lo stesso motivo.
Leggi il motivo su quella riga. Le cause comuni sono una prop che l'elemento non accetta e un elemento che l'app non ha.
`$.ui.open` viene eseguito e nessun riquadro appare
La chiamata non è venuta da qualcosa che l'utente ha fatto e il terminale è più stretto di 144 colonne.
Apri il riquadro da un comando o un pulsante, oppure controlla il risultato isPlaced della chiamata. Vedi Open a pane at the right time.
I tasti di scelta rapida non fanno nulla
Il tuo riquadro non ha il focus della tastiera.
Premi Ctrl+X quindi Tab, oppure fai clic sul riquadro. Aprilo con focus: true da un comando.
Un disegno funziona nel terminale e non nell'app Desktop
Il sito o l'elemento non è disponibile lì.
Controlla le render sites e le tabelle elements.
Una modifica o un valore viene perso
Il mod viene eseguito e una modifica che hai fatto o un valore che ha mantenuto non è lì.
Le tue modifiche non hanno effetto
Stai modificando un plugin che hai installato. Claude Code esegue la copia memorizzata nella cache per la versione installata.
Sviluppa con --plugin-dir puntato alla tua copia di lavoro, come in claude --plugin-dir ./first-mod, che ricarica quando salvi.
Un valore si ripristina quando il modulo si ricarica
Le variabili a livello di modulo vengono reinizializzate ad ogni ricaricamento.
Mantieni il valore in $.state o $.store.
Un valore si ripristina dopo `/clear`, `/resume` o `/branch`
Un valore si ripristina, oppure un valore salvato viene sostituito dal suo valore predefinito. Ognuno di questi comandi ripristina $.state ai suoi valori predefiniti e session.start non si attiva di nuovo.
Carica il valore salvato di nuovo in un hook classic.SessionStart.
Read the debug log
Il debug log ha una riga per ogni modulo che Claude Code carica o rifiuta, ogni hook che fallisce e ogni risultato che rifiuta, quindi è dove guardare quando la trascrizione non mostra nulla. Per scriverne uno, nella tua shell avvia Claude Code con --debug, oppure con --debug-file <path> per scegliere dove va:
claude --debug-file ./mod-debug.log --plugin-dir ./first-mod
In un altro terminale, segui il file e filtra per il nome del tuo mod:
tail -f ./mod-debug.log | grep first-mod
Un mod che si è caricato ha una riga che lo nomina ed elenca gli eventi che aggancia. Un mod caricato con --plugin-dir appare sotto il suo nome seguito da @inline:
hooks module first-mod@inline loaded (worker, environment 2, tier user); events: session.start,tool.call,command.run,ui.render
Un disegno che non ha convalidato conta come un risultato rifiutato e ottiene una riga anche. Per scrivere le tue righe nel log, chiama $.ui.log con un secondo argomento, come in $.ui.log('message', { to: 'debug' }). Senza il secondo argomento, $.ui.log aggiunge una riga attenuata alla trascrizione.
Mentre modifichi un mod caricato con --plugin-dir, la trascrizione mostra una riga per ogni ricaricamento che nomina il mod ed elenca i suoi hooks. Se un salvataggio interrompe il modulo, la riga dice reload failed, the previous version stays loaded: con il motivo e l'ultima versione funzionante continua a essere eseguita.
Next steps
- Test a mod: cattura i problemi prima che raggiungano una sessione
- Troubleshoot plugins: problemi con l'installazione e il caricamento di un plugin che non sono specifici dei mod