SpyBara
Go Premium

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

This page contains 88 additions and 86 deletions.

2026
Thu 1 23:59 Fri 2 22:59

Risolvere i problemi di un mod

Scopri perché un mod di Claude Code non fa nulla: associa il sintomo o il messaggio alla sua causa, cerca i messaggi di rifiuto e leggi il log di debug.

Quando il modulo di un mod o uno dei suoi hook non funziona, Claude Code lo salta e la sessione continua, quindi un mod difettoso può sembrare un mod che non fa nulla. Inizia verificando cosa Claude Code ha letto dal tuo mod e dove segnala un problema, poi cerca il sintomo o il messaggio che hai riscontrato.

Scopri perché un mod non fa nulla

Quando un mod non fa nulla, controlla cosa legge Claude Code dai file del mod e la riga che scrive quando salta qualcosa. Per il primo punto, nella tua shell esegui claude plugin validate con la directory del mod, come in claude plugin validate ./first-mod. Individua un evento scritto in modo errato, un manifest non valido e un modulo che Claude Code non riesce a leggere, senza avviare una sessione.

Quando un modulo non viene caricato, 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. Si tratta di una sessione interattiva che hai avviato con --plugin-dir, oppure di una in cui hai abilitato il ricaricamento a caldo per i mod scritti da Claude.
  • Qualsiasi altra sessione interattiva, come una che esegue un mod installato da un marketplace: solo il log di debug. Per ottenerlo, avvia la sessione con claude --debug.
  • Un'esecuzione di claude -p con --plugin-dir: stderr, nel formato di output di testo predefinito. Un rifiuto da parte di un altro mod finisce solo nel log di debug.

Verificare se i mod possono essere caricati

Per verificare se la tua configurazione consente in generale il caricamento dei mod, senza installarne uno, esegui claude plugin test nella tua shell, da una directory che non contiene un mod. Non ti serve una sessione. Il messaggio che viene stampato ti indica lo stato:

Il messaggio include Cosa significa
no hooks module to load I mod possono essere caricati. Il comando non ha trovato alcun mod da testare in questa directory.
hooks modules are turned off here Un'impostazione sta bloccando i tuoi mod: disableAllHooks nelle tue impostazioni oppure la policy della tua organizzazione
hooks modules are turned off in this process Anthropic ha disattivato da remoto i mod installati. Nessuna impostazione sulla tua macchina li riattiva.

Un'organizzazione può anche impostare allowManagedModsOnly per consentire solo i propri mod, cosa che questo comando non segnala. In tal caso un mod che installi non viene caricato e un messaggio ne spiega il motivo.

Il mod non si carica

Non compare nulla di ciò che il mod aggiunge: nessun comando, nessun elemento disegnato e nessun cambiamento di comportamento.

La tua versione è precedente alla 2.1.287

claude --version stampa una versione precedente alla 2.1.287. La tua versione è anteriore all'attivazione predefinita dei mod.

Aggiorna Claude Code.

La riga `mods active` non nomina il mod

Non compare nulla di ciò che il mod aggiunge, e la riga mods active in /plugin non lo nomina. Il modulo degli hook non è stato caricato. Quando Claude Code lo ha rifiutato, il log di debug contiene 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 messaggi di rifiuto li elenca tutti. Se il log non contiene una riga del genere, verifica le altre voci di questo gruppo.

Alcune impostazioni bloccano un mod e lasciano funzionante il resto del suo plugin. Attivare o disattivare i mod le elenca.

Un'esecuzione di `claude -p` stampa `hooks module not loaded`

La riga inizia con il nome del mod e viene scritta su stderr. Il modulo degli hook è stato rifiutato. Un'esecuzione non interattiva non ha una trascrizione, quindi il messaggio viene scritto su stderr.

Leggi il motivo dopo i due punti. La sezione messaggi di rifiuto li elenca tutti.

Messaggi di rifiuto

Ciascuno di questi segue hooks module, il nome del mod e not loaded: nel log di debug.

Il messaggio inizia con Cosa significa
hooks modules are turned off for installed plugins in this process Anthropic ha disattivato da remoto i mod installati. Nessuna impostazione sul tuo computer li riattiva.
disableAllHooks in managed settings La tua organizzazione ha disattivato gli hook dei plugin installati
only managed plugins and built-in plugins run È impostato allowManagedHooksOnly, 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 hanno lo stesso nome. Viene usato quello gestito, oppure quello caricato per primo.

Messaggi della protezione integrata

Su un computer con impostazioni gestite, o per un utente che ha effettuato l'accesso con un piano Team o Enterprise, la protezione integrata 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 propri mod, quindi il tuo non è stato caricato Il log di debug e la trascrizione in una sessione che ricarica a caldo una directory di plugin
tried to lift a deny rule in your settings L'hook tool.check del tuo mod ha approvato una chiamata che una regola deny rifiuta. La chiamata resta negata. La trascrizione e il log di debug, una volta per ogni mod in una sessione. In un'esecuzione di claude -p, solo il log di debug.
the deny rules in your settings could not be checked for this call, so it is refused La protezione non è riuscita a completare la verifica di una chiamata approvata da un mod, quindi ha rifiutato la chiamata Il motivo che Claude legge per la chiamata negata

`validate` ha esito positivo e non elenca alcuna riga `hooks`

hooks/hooks.json non ha una chiave modules, oppure la chiave è scritta in modo errato.

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

`hooks module did not load`

La riga inizia con il nome del mod, seguito da hooks module did not load: e da un motivo, che indica il file e la riga quando il problema è nel tuo codice. Claude Code non è riuscito a caricare il modulo, ad esempio perché il suo codice di primo livello ha generato un'eccezione.

Correggi l'errore indicato dal motivo.

`options do not fit plugin.json userConfig`

La riga inizia con il nome del mod, seguito da hooks module did not load: options do not fit plugin.json userConfig: e da un motivo. Un'opzione non supera la validazione rispetto al suo campo userConfig, ad esempio un numero superiore al max del campo, oppure un campo obbligatorio non ha un valore.

Imposta o modifica il valore. La fine della riga indica la relativa voce pluginConfigs in settings.json.

Nessun mod si carica in una directory aperta per la prima volta

Non hai risposto alla richiesta di attendibilità per la directory.

Avvia una sessione interattiva in quella directory con claude e accetta la richiesta di attendibilità con cui si apre.

Nessun plugin installato si carica

Hai avviato Claude Code con --safe-mode.

Avvialo senza il flag.

Un hook viene saltato o un mod viene scaricato

Il mod è stato caricato, e poi Claude Code ha saltato uno dei suoi hook o lo ha scaricato.

`hook skipped`

La riga indica il mod e l'evento, poi riporta hook skipped: e un motivo, come in first-mod: tool.call hook skipped: threw Error: boom. Un hook ha generato un'eccezione, ha superato il suo limite di tempo o ha restituito un risultato con una struttura errata. La riga compare una volta per ogni evento e tipo di errore finché il mod non viene ricaricato.

Correggi l'errore. Il log di debug contiene una riga per ogni occorrenza.

`no command.run hook answered it`

Esegui un comando aggiunto dal tuo mod e la risposta indica il mod e il comando, come in first-mod registered /tally but no command.run hook answered it, poi ti dice di aggiungere un hook. Claude Code stampa questa risposta quando il comando raggiunge la fine della catena senza una risposta, cosa che accade in due casi:

  • Nessun hook ha risposto al comando: il modulo non ha un hook command.run, il filtro dell'hook indica un comando diverso, oppure l'hook ha restituito next(e)
  • Claude Code ha saltato l'hook: hook skipped elenca i motivi. Passare focus: false a $.ui.open è uno dei modi in cui si arriva a questa situazione.

Se il modulo ha già l'hook descritto dalla risposta, cerca una riga hook skipped che indichi command.run, la quale riporta il motivo. Un test che esegue il comando fallisce con lo stesso motivo.

`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 unico worker thread. Il worker ha smesso di rispondere o si è arrestato in modo anomalo, e Claude Code ne ha attribuito la causa a questo mod e lo ha scaricato. Un hook che blocca il thread, come un ciclo che non esegue mai un await, è una delle possibili cause.

Correggi l'hook.

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

La riga riporta 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 è riuscito ad attribuire gli arresti a un singolo mod, quindi ha scaricato tutti i mod non integrati, compresi quelli installati dalla tua organizzazione. Questa riga compare nella trascrizione in ogni sessione interattiva.

Esegui /reload-plugins per caricarli di nuovo.

Una chiamata a uno strumento viene negata

Il mod è stato caricato e i suoi hook vengono eseguiti, ma una chiamata a uno strumento su cui ha agito viene rifiutata.

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

In modalità auto, una chiamata a uno strumento negata riporta questo motivo. Un hook ha modificato l'input della chiamata allo strumento dopo che il classificatore lato server l'aveva esaminata, quindi quella revisione non copre ciò che verrebbe eseguito. L'hook può essere un hook tool.call o turn.step di un mod, oppure un hook delle impostazioni PreToolUse. Il messaggio non indica quale.

Il messaggio dice a Claude di effettuare la chiamata ancora una volta così come è stata registrata. Se anche quella viene negata, l'hook modifica l'input ogni volta, quindi disattiva il mod o l'hook, oppure esci dalla modalità auto e approva tu stesso la chiamata.

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 protezione integrata.

Cercali in Messaggi dalla protezione integrata.

Un disegno non appare o non risponde

Il mod è stato caricato, ma il suo riquadro, la sua banda o i suoi controlli non si comportano come ti aspetti.

Un riquadro o una banda è vuota o mostra il contenuto abituale di Claude Code

L'albero restituito dal tuo hook non ha superato la convalida. Con --plugin-dir, la trascrizione riporta ui.render (Pane) refused: seguito dal 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 log di debug contiene 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 possiede.

`$.ui.open` viene eseguito e nessun riquadro appare

La chiamata non è partita da un'azione dell'utente e il terminale è più stretto della larghezza richiesta da quel riquadro.

Apri il riquadro da un comando o da un pulsante, oppure controlla il risultato isPlaced della chiamata. Consulta Aprire un riquadro al momento giusto.

I tasti di scelta rapida non fanno nulla

Il tuo riquadro non ha il focus della tastiera.

Premi Ctrl+X e poi Tab, oppure fai clic sul riquadro. Aprilo con focus: true da un comando.

Un disegno funziona nel terminale ma non nell'app Desktop

Il punto di rendering o l'elemento non è disponibile lì.

Controlla le tabelle dei punti di rendering e degli elementi.

Una modifica o un valore va perso

Il mod viene eseguito, ma una modifica che hai apportato o un valore che ha mantenuto non è presente.

Le tue modifiche non hanno effetto

Stai modificando un plugin che hai installato. Claude Code esegue la copia nella cache per la versione installata.

Sviluppa con --plugin-dir puntato alla tua copia di lavoro, come in claude --plugin-dir ./first-mod, che si ricarica quando salvi.

Un valore si reimposta quando il modulo si ricarica

Le variabili a livello di modulo vengono reinizializzate a ogni ricaricamento.

Mantieni il valore in $.state o $.store.

Un valore si reimposta dopo `/clear`, `/resume` o `/branch`

Un valore si reimposta, oppure un valore salvato viene sostituito dal suo valore predefinito. Ciascuno di questi comandi reimposta $.state ai valori predefiniti e session.start non viene attivato di nuovo.

Carica di nuovo il valore salvato in un hook classic.SessionStart.

Leggere il log di debug

Il log di debug contiene una riga per ogni modulo che Claude Code carica o rifiuta, per ogni hook che fallisce e per ogni risultato che rifiuta, quindi è il posto in cui 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 salvarlo:

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 è stato caricato ha una riga che lo nomina ed elenca gli eventi che gestisce. Un mod caricato con --plugin-dir compare con 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

Anche un disegno che non ha superato la validazione conta come risultato rifiutato e ottiene una riga. 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 hook. Se un salvataggio rompe il modulo, la riga riporta reload failed, the previous version stays loaded: con il motivo, e l'ultima versione funzionante continua a essere eseguita.

Passaggi successivi