> ## 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.
# 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`](/docs/it/plugins/mods/create#check-what-claude-code-reads-from-your-mod) 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](/docs/it/plugins/mods/create#ask-claude-for-a-mod) 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](#read-the-debug-log) solo. Per ottenerne uno, avvia la sessione con `claude --debug`.
* **Un'esecuzione `claude -p` con `--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é](/docs/it/plugins/mods/troubleshoot#messages-from-the-built-in-guard).
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.
[Aggiorna Claude Code](/docs/it/setup#update-claude-code).
La riga `mods active` non nomina il mod
Nulla di ciò che il mod aggiunge appare e la [`riga mods active`](/docs/it/plugins/mods/overview#see-which-mods-a-session-loaded) 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](#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](#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](/docs/it/plugins/mods/admin#know-what-happens-by-default) 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](/docs/it/plugins/mods/admin#install-your-organizations-mods), quindi il tuo non è stato caricato | Il debug log e la trascrizione in una [sessione che ricarica a caldo una directory di plugin](#find-out-why-a-mod-does-nothing) |
| `tried to lift a deny rule in your settings` | Il [`tool.check`](/docs/it/plugins/mods/reference#tools) 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`](/docs/it/plugins/components#user-configuration), 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](/docs/it/plugins/mods/reference#limits), 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.
Il mod si è caricato e i suoi hooks vengono eseguiti e una chiamata di strumento che ha toccato viene rifiutata.
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](/docs/it/permission-modes#server-side-classifier-review) lo ha esaminato, quindi quella revisione non copre ciò che verrebbe eseguito. L'hook può essere il [`tool.call`](/docs/it/plugins/mods/reference#tools) o il [`turn.step`](/docs/it/plugins/mods/reference#turns) hook del mod, oppure un hook di impostazioni [`PreToolUse`](/docs/it/hooks#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](#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](/docs/it/plugins/mods/interface#build-a-tree-from-elements) 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](/docs/it/plugins/mods/interface#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](/docs/it/plugins/mods/reference#render-sites) e le tabelle [elements](/docs/it/plugins/mods/reference#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`](/docs/it/plugins/mods/interface#keep-state).
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](/docs/it/plugins/mods/interface#load-a-saved-value-again-after-clear) 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 ` per scegliere dove va:
```bash theme={null}
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:
```bash theme={null}
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`:
```text theme={null}
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`](/docs/it/plugins/mods/api#show-something-without-starting-a-turn) 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](/docs/it/plugins/mods/test): cattura i problemi prima che raggiungano una sessione
* [Troubleshoot plugins](/docs/it/plugins/troubleshooting): problemi con l'installazione e il caricamento di un plugin che non sono specifici dei mod