Risolvere i problemi dei plugin

Correggi gli errori dei plugin in Claude Code. Trova il messaggio esatto che hai visto, raggruppato per fase da dove /plugin viene eseguito fino all'installazione e alla politica organizzativa.

Questa pagina elenca i messaggi di errore e i sintomi per i plugin di Claude Code e per i marketplace, i cataloghi da cui Claude Code installa i plugin. Ogni voce fornisce la causa, una soluzione e cosa vedi una volta che la soluzione funziona.

Dove un messaggio nomina un plugin o un marketplace, la voce mostra un segnaposto come <name> al suo posto.

Utilizza questa pagina che tu stia installando plugin, costruendoli, ospitando un marketplace o amministrando plugin per un'organizzazione.

Cerca il messaggio esatto che hai visto. Ogni messaggio è elencato sotto la fase che lo produce, che non è sempre il comando che hai eseguito. Ad esempio, un'installazione può fallire perché manca un marketplace, quindi quel messaggio è sotto Add a marketplace.

Find where `/plugin` runs

/plugin è un comando che si digita all'interno di una sessione di terminale Claude Code in esecuzione e apre un pannello interattivo. Le voci in questa sezione coprono i luoghi in cui è possibile digitarlo ma non può essere eseguito e i comandi che non esistono.

`/plugin isn't available in this environment`

È stato digitato /plugin da qualche parte diversa da una sessione di terminale Claude Code e Claude ha risposto con questa riga invece di aprire qualcosa.

Si riceve questa risposta in una sessione che non ha un terminale per disegnare il pannello /plugin in: non-interactive mode con claude -p, l'Agent SDK, la scheda Code dell'app desktop Claude, il pannello dell'estensione VS Code e il browser su claude.ai/code.

Nel pannello dell'estensione VS Code, solo una riga /plugin con qualcosa dopo di essa, come /plugin install <plugin>@<marketplace>, riceve questa risposta. /plugin o /plugins digitati da soli aprono la finestra di dialogo Manage plugins.

Installare il plugin dalla superficie su cui ci si trova:

• App desktop Claude, sessione locale o SSH: fare clic sul pulsante + accanto al prompt, quindi Plugins, quindi Add plugin per aprire il plugin browser
• Estensione VS Code: utilizzare la scheda VS Code sotto Install a plugin
• Claude Code sul web o una sessione cloud desktop: una sessione cloud non ha un browser di plugin. Vedere la scheda Cloud session sotto Install a plugin per ciò che una sessione cloud carica
• Un terminale a cui si ha accesso: eseguire claude e digitare /plugin lì, oppure eseguire claude plugin install <plugin>@<marketplace> nella shell senza avviare una sessione

Quando un'installazione da terminale funziona, /plugin stampa un riepilogo di installazione che inizia con ✓ Installed <plugin>. e claude plugin install stampa Successfully installed plugin: <plugin>@<marketplace>.

`zsh: no such file or directory: /plugin`

È stato digitato /plugin ... al prompt della shell e la shell ha segnalato che non esiste alcun file denominato /plugin. Bash segnala bash: /plugin: No such file or directory.

/plugin è un comando che si digita all'interno di una sessione Claude Code, non al prompt della shell. Avviare una sessione e digitare lo stesso comando lì:

claude

Quindi, al prompt di Claude Code:

/plugin install <plugin>@<marketplace>

Un'installazione riuscita stampa un riepilogo che inizia con ✓ Installed <plugin>. Se l'installazione stessa fallisce, il suo messaggio è sotto Add a marketplace o Install a plugin.

Per installare dalla shell senza avviare una sessione, eseguire claude plugin install <plugin>@<marketplace> al suo posto.

`The term '/plugin' is not recognized as the name of a cmdlet`

È stato digitato /plugin ... al prompt di PowerShell e /plugin è un comando Claude Code, non un programma. Bash e Zsh segnalano la loro forma di questo errore.

Utilizzare uno di questi al suo posto:

• Eseguire claude, quindi digitare /plugin al prompt di Claude Code
• Eseguire claude plugin install <plugin>@<marketplace> in PowerShell senza avviare una sessione

`claude: command not found` after `claude plugin ...`

È stato eseguito claude plugin install ... nella shell e la shell non ha potuto trovare claude affatto. Su Windows il messaggio è 'claude' is not recognized as the name of a cmdlet o 'claude' is not recognized as an internal or external command.

La causa non è il comando del plugin. O Claude Code non è installato, oppure la sua directory di installazione non è su PATH in questa shell. Seguire command not found: claude after installation, quindi riprovare il comando del plugin.

`Unknown command` and command spellings that don't exist

È stato digitato un comando di plugin visto da qualche parte e si è ricevuto Unknown command: /<name> in una sessione, o error: unknown command '<name>' o error: unknown option '<flag>' dal binario claude nella shell.

Diversi comandi sono in uso che Claude Code non ha. La tabella seguente mappa ciascuno al comando reale. Il plugin commands reference elenca ogni sottocomando e flag.

Questi comandi sembrano sbagliati ma funzionano:

• claude plugins è un alias di claude plugin
• claude plugin remove è un alias di claude plugin uninstall
• /plugins e /marketplace in una sessione aprono lo stesso pannello di /plugin

Add a marketplace

Un marketplace è un catalogo che si aggiunge a Claude Code da un repository git, un URL o un percorso locale. Queste voci coprono i messaggi che si ricevono quando l'aggiunta fallisce o un successivo aggiornamento fallisce.

`Marketplace "claude-plugins-official" not found`

È stato eseguito /plugin install <plugin>@claude-plugins-official in una sessione e Claude Code ha segnalato che non ha alcun marketplace con quel nome.

Il marketplace ufficiale non è ancora registrato su questa macchina. Claude Code normalmente lo registra da solo la prima volta che si avvia una sessione di terminale interattiva. Non è stato eseguito se si è utilizzato Claude Code solo attraverso l'estensione VS Code e salta o rinvia quel passaggio:

• Quando una politica blocca la fonte
• Quando CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL è impostato
• Dopo un tentativo fallito che sta aspettando di riprovare

I comandi della shell claude plugin non lo registrano mai per voi.

Aggiungerlo, quindi riprovare l'installazione:

/plugin marketplace add anthropics/claude-plugins-official

Claude Code stampa Successfully added marketplace: claude-plugins-official e /plugin marketplace list mostra il marketplace con la sua fonte.

Per qualsiasi altro nome di marketplace in questo messaggio, vedere Marketplace "<name>" not found.

La stessa stringa appare anche nella scheda Errors di /plugin, l'elenco dei fallimenti di caricamento del pannello, quando un plugin elencato nelle impostazioni nomina un marketplace che non è stato aggiunto.

`Marketplace "" not found`

È stato eseguito /plugin install in una sessione e Claude Code ha segnalato che non ha alcun marketplace con quel nome. Due forme del comando raggiungono questo messaggio:

• /plugin install <plugin>@<name>: la riga di installazione, spesso una che qualcuno ha inviato, nomina un marketplace che non è stato aggiunto. Il resto di questa voce copre come trovarlo e aggiungerlo.
• /plugin install <source> con un percorso, URL o owner/repo: questa forma segnala il messaggio invece di installare, anche per una fonte che è già stata aggiunta. Per installare da una fonte in un comando, vedere Add a marketplace and install in one command.

Se il nome inizia con claudeai-, il marketplace è ospitato su claude.ai e lo si aggiunge per nome dalla shell con claude plugin marketplace add --claudeai <name>. Vedere Add a marketplace from claude.ai.

Per qualsiasi altro nome, una riga di installazione nomina un marketplace ma non dice dove è ospitato il marketplace e Claude Code non ha un indice per cercare un nome di marketplace. Chiedere a chi ha inviato la riga la fonte del marketplace, che è un GitHub owner/repo, un URL git o un percorso. Quindi aggiungere il marketplace ed eseguire di nuovo la riga di installazione.

Un marketplace che qualcuno invia è di terze parti, quindi rivedere il plugin prima di installarlo.

Se il marketplace è già stato aggiunto, controllare l'ortografia rispetto a /plugin marketplace list.

`Invalid marketplace source format`

È stato eseguito /plugin marketplace add <source> o claude plugin marketplace add <source> e Claude Code ha risposto Invalid marketplace source format. Try: owner/repo, https://..., or ./path.

Claude Code accetta una fonte in una di queste forme:

• Un shorthand GitHub owner/repo
• Un URL https:// o http://
• Un URL SSH user@host:path
• Un percorso locale che inizia con ./, ../, / o ~

Un nome semplice come claude-plugins-official non corrisponde a nessuno di essi. Nemmeno un nome host semplice come marketplace.anthropic.com.

Riscrivere la fonte in una delle forme accettate:

/plugin marketplace add anthropics/claude-plugins-official

Claude Code stampa Successfully added marketplace: <name> quando l'aggiunta funziona.

`'' is not a valid GitHub owner/repo shorthand`

È stata passata una fonte con una barra che non è owner/repo, come github.com/owner/repo o un percorso gitlab.example.com/group/project. Claude Code l'ha rifiutata con questo messaggio e un elenco di forme accettate.

Lo shorthand owner/repo è solo per GitHub e deve seguire le regole di denominazione di GitHub, quindi un nome host o un segmento di percorso aggiuntivo fallisce. Passare la fonte nella forma che corrisponde a dove è ospitato il marketplace:

• Un repository su qualsiasi host: l'URL di clonazione completo
• Un marketplace.json ospitato: il suo URL https://
• Un checkout locale: ./path o un percorso assoluto

Ad esempio, per aggiungere il marketplace ufficiale tramite il suo URL di clonazione, in una sessione:

/plugin marketplace add https://github.com/anthropics/claude-plugins-official.git

Un'aggiunta riuscita stampa Successfully added marketplace: <name>.

`Invalid git URL`

È stato aggiunto un marketplace, installato un plugin o eseguito un aggiornamento da un indirizzo git e il comando è fallito con Invalid git URL nel suo messaggio.

Claude Code controlla ogni indirizzo git prima di eseguire git. Rifiuta un indirizzo il cui protocollo non supporta. Rifiuta anche un indirizzo che git potrebbe leggere come denominazione di un server o cartella diversa da quella che l'indirizzo mostra.

Il testo dopo l'indirizzo nomina cosa cambiare. Riscrivere l'indirizzo come il messaggio dice ed eseguire di nuovo il comando.

Un rifiuto che invece dice is blocked by enterprise policy proviene dalle impostazioni dell'organizzazione. Vedere Marketplace source is blocked by enterprise policy.

`Path does not exist: `

È stato passato un percorso locale a marketplace add e nulla esiste in quel percorso. Un percorso relativo si risolve rispetto alla directory corrente.

Controllare il percorso risolto nel messaggio. Quindi eseguire il comando dalla directory da cui inizia il percorso relativo, o passare un percorso assoluto alla directory del marketplace. Un'aggiunta riuscita stampa Successfully added marketplace: <name>.

Claude Code accetta una directory che contiene .claude-plugin/marketplace.json o un percorso a un file .json. Un percorso a qualsiasi altro file fallisce con File path must point to a .json file (marketplace.json).

`Marketplace file not found at /.claude-plugin/marketplace.json`

Claude Code ha clonato o scaricato il marketplace ma non ha trovato marketplace.json nel percorso previsto al suo interno. Il comando di aggiunta lo segnala come Failed to add marketplace: Marketplace file not found at ....

La posizione predefinita è .claude-plugin/marketplace.json alla radice del repository e il marketplace reference elenca le posizioni accettate.

La soluzione differisce per il proprietario e per tutti gli altri:

• Si possiede il marketplace: mettere il file in quella posizione e re-aggiungere il marketplace
• Qualcun altro lo ospita: chiedere al proprietario la fonte esatta che pubblica

`SSH authentication failed` or `HTTPS authentication failed`

È stato aggiunto o aggiornato un marketplace da un repository git e il clone è fallito con Failed to clone marketplace repository: seguito da una di queste righe.

Per prima cosa controllare il repository stesso: un owner/repo scritto male, un repository che non esiste o un repository privato che non si può vedere termina anche con questo messaggio. Aprire l'URL del repository nel browser o eseguire git ls-remote <url> nel terminale per confermare che esiste e che si ha accesso.

Se il repository è corretto, la causa è le credenziali. Claude Code esegue git con i prompt interattivi disabilitati, quindi non può chiedere una password, una passphrase della chiave o una credenziale come farebbe il terminale. Se git ha bisogno di un prompt, si vede fatal: Cannot prompt because user interactivity has been disabled o terminal prompts disabled nell'errore originale. Solo le credenziali che già funzionano in modo non interattivo hanno successo:

• SSH: ssh -T git@<host> deve avere successo senza chiedere una passphrase e l'host deve già essere in known_hosts
• HTTPS: l'helper delle credenziali deve contenere un token per l'host. Per GitHub, eseguire gh auth login e gh auth setup-git. Per un altro host, memorizzare un token di accesso personale nell'helper delle credenziali git. Testare con git ls-remote <url>

Una volta che git ls-remote ha successo nel terminale senza un prompt, eseguire di nuovo l'aggiunta o l'aggiornamento. Un'aggiunta riuscita stampa Successfully added marketplace: <name>. Un aggiornamento riuscito stampa Successfully updated marketplace: <name> dalla shell o ✔ Updated 1 marketplace in una sessione.

Per fare in modo che Claude Code salti SSH per le fonti GitHub owner/repo, impostare CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1. Senza di esso, Claude Code clona quelle fonti su SSH quando una chiave SSH per github.com sembra configurata e torna a HTTPS quando il clone SSH fallisce.

Per ciò che gli aggiornamenti automatici in background possono e non possono fare con le credenziali, vedere What background auto-update does with credentials.

`SSH host key is not in your known_hosts file`

È stato aggiunto un marketplace su SSH da un host a cui non ci si è mai connessi e il clone è fallito con questa riga e un suggerimento ssh -T git@<host>. Per un host la cui chiave è cambiata, il messaggio è SSH host key has changed con un suggerimento ssh-keygen -R <host> al suo posto.

Claude Code clona con StrictHostKeyChecking=yes, quindi rifiuta un host la cui chiave non è stata ancora accettata piuttosto che accettare la chiave automaticamente. Connettersi una volta dal terminale per accettare l'impronta digitale, quindi riprovare:

ssh -T git@github.com

Per un repository pubblico, aggiungere il marketplace tramite il suo URL https:// al suo posto per evitare completamente SSH.

`Command 'git' not found or is in an unsafe location`

Su Windows, è stato aggiunto un marketplace e Claude Code ha segnalato Failed to clone marketplace repository: Command 'git' not found or is in an unsafe location (current directory).

Claude Code cerca git su PATH e rifiuta di eseguirne uno trovato solo nella directory corrente. Per correggerlo, installare Git e riprovare:

`Git clone timed out after 120s`

È stato aggiunto o aggiornato un marketplace e ha fallito con Git clone timed out after 120s, seguito da un suggerimento per impostare CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS.

La clonazione di un marketplace e la re-clonazione per aggiornarlo ottiene 120 secondi per impostazione predefinita. Per un repository di grandi dimensioni o una connessione lenta, aumentare il limite. Il valore è in millisecondi:

export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000

$env:CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS = "300000"

Quindi riprovare nella stessa shell.

Se il repository è un monorepo, limitare il checkout alle directory che si nominano con claude plugin marketplace add <source> --sparse <paths>.

Marketplace updates keep failing offline

Si lavora in un ambiente in cui l'host git del marketplace non è raggiungibile e ogni sessione ripete un aggiornamento fallito in background. Il checkout esistente del marketplace rimane in posizione e l'avvio non è ritardato.

Ogni sessione, per un marketplace con auto-update on, Claude Code controlla l'host git del marketplace per nuovi commit in background. Quando quel controllo non può raggiungere l'host, tenta di clonare di nuovo il marketplace e offline anche quel clone fallisce.

Impostare questa variabile per saltare il tentativo di re-clone e continuare a utilizzare il checkout esistente quando il controllo non può raggiungere l'host:

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

$env:CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE = "1"

Con la variabile impostata, Claude Code salta il re-clone solo per un checkout che contiene già .claude-plugin/marketplace.json. Un marketplace che non è mai stato clonato o il cui clone si è fermato a metà ottiene comunque il tentativo di clone, quindi aggiungerlo una volta mentre online.

Per una distribuzione completamente offline, pre-popolare la directory dei plugin al momento della compilazione dell'immagine con CLAUDE_CODE_PLUGIN_SEED_DIR al suo posto, seguendo Seed containers and CI.

Marketplace add fails on a GitHub Enterprise Server host

È stato aggiunto un marketplace da un URL GitHub Enterprise Server (GHES) e si è ricevuto un errore di politica, oppure è stato aggiunto da claude.ai e si è ricevuto un errore di accesso a GitHub.

Entrambi i casi sono sulla pagina GHES:

• Un errore di politica significa che l'organizzazione ha limitato le fonti del marketplace e un amministratore deve aggiungere un hostPattern per l'host
• Un errore di accesso a GitHub su claude.ai significa che il proprio account GitHub Enterprise non è ancora connesso

Install a plugin

Hai aggiunto un marketplace e hai eseguito un'installazione, ma l'installazione si è fermata con un messaggio invece di installare qualcosa. Queste voci coprono quei messaggi. Coprono anche i messaggi correlati che appaiono in seguito nella scheda Errors di /plugin, o come una scheda Discover vuota, quando un plugin o il suo marketplace non può essere trovato, letto o considerato attendibile.

`Plugin "" not found in marketplace ""`

Hai eseguito /plugin install <name>@<marketplace> o claude plugin install <name>@<marketplace> e il nome del plugin non è nella copia del catalogo di quel marketplace sulla tua macchina.

claude plugin install nella shell stampa lo stesso messaggio quando non hai aggiunto affatto il marketplace. Se claude plugin marketplace update <marketplace> risponde quindi con Marketplace '<marketplace>' not found, aggiungi prima il marketplace.

`not found in marketplace` with a refresh hint

Il suggerimento recita Your local copy may be out of date — try claude plugin marketplace update <marketplace> o The marketplace couldn't be refreshed (...). Claude Code non ha aggiornato il marketplace prima della ricerca, ad esempio quando sei offline, quindi la tua copia del catalogo potrebbe essere obsoleta. Aggiorna usando il nome del marketplace, quindi installa di nuovo:

/plugin marketplace update <marketplace>

claude plugin marketplace update stampa Successfully updated marketplace: <name> e /plugin marketplace update mostra ✔ Updated 1 marketplace. Se il nuovo tentativo di installazione stampa lo stesso messaggio, controlla il nome come descritto in not found in marketplace with no hint. When Claude Code refreshes a marketplace before an install elenca gli altri casi in cui l'aggiornamento non viene eseguito.

`not found in marketplace` with no hint

Il nome è il problema più probabile. Apri /plugin, vai su Discover e copia il nome dall'elenco.

Prima della v2.1.232, Claude Code aggiornava il marketplace indicato solo dopo che la ricerca non aveva trovato il plugin, e solo quando l'aggiornamento automatico era attivo per quel marketplace.

`Plugin "" not found in any marketplace`

Hai eseguito /plugin install <name> senza @marketplace e nessun marketplace registrato ha quel plugin. claude plugin install <name> segnala Plugin "<name>" not found in any configured marketplace.

Senza un nome di marketplace, claude plugin install cerca nei cataloghi che ha già e non li aggiorna prima, mentre /plugin install aggiorna solo i marketplace che hanno l'aggiornamento automatico attivo. Indica il marketplace e Claude Code lo aggiornerà prima di cercare il plugin:

/plugin install <name>@<marketplace>

Quando l'installazione funziona, vedi ✓ Installed <plugin>. in una sessione o Successfully installed plugin: <plugin>@<marketplace> da claude plugin install.

Se non sai quale marketplace elenca il plugin, esegui /plugin marketplace list per vedere i marketplace che hai e sfoglia Discover in /plugin per cercare il nome del plugin.

`Plugin '@' is already installed globally`

Hai eseguito /plugin install per un plugin che è già installato nell'ambito utente o tramite impostazioni gestite, e Claude Code ha rifiutato con Use '/plugin' to manage existing plugins. Se hai digitato il nome del plugin senza @<marketplace>, il messaggio omette globally.

Il plugin è già disponibile in ogni progetto, quindi non c'è nulla da aggiungere. Per modificarne l'ambito, abilitarlo o disabilitarlo, o configurarlo, apri /plugin e vai su Installed.

Un plugin installato solo nell'ambito di progetto o locale non attiva questo messaggio. Claude Code ti consente di installarlo anche nell'ambito utente, così è disponibile in altri progetti.

claude plugin install nella shell stampa un messaggio diverso. Per un plugin già installato nell'ambito di destinazione, stampa Plugin "<name>@<marketplace>" is already installed (scope: user) ed esce con 0. Se la sua directory nella cache è mancante, lo stesso comando la scarica di nuovo.

`"" was not installed: it would share its folder with ""`

Hai installato un plugin tramite claude plugin install, /plugin o un suggerimento di installazione in una sessione, e Claude Code l'ha rifiutato con questa riga o con would share its saved data with.

L'id del plugin rifiutato e l'id di un plugin installato corrispondono alla stessa cartella su disco: sono uguali una volta che . e @ vengono scritti come -. Su macOS e Windows, anche gli id che differiscono solo per le maiuscole corrispondono alla stessa cartella. Installarli entrambi metterebbe i file di un plugin nella cartella dell'altro, quindi Claude Code rifiuta e il plugin installato mantiene i suoi file.

Il messaggio indica la via d'uscita:

• L'altro plugin è installato: il messaggio dice Only one of the two can be installed. e indica il comando claude plugin uninstall, o il passaggio di disinstallazione in /plugin, che rimuove l'altro plugin. Eseguilo, quindi installa di nuovo. Per sapere cosa rimuove la disinstallazione, consulta What an uninstall deletes and keeps.
• Entrambi gli id arrivano in un'unica installazione, come un plugin e una dipendenza di cui ha bisogno: nessun ordine di installazione aiuta. Solo un manutentore del marketplace che elenca i due plugin può risolvere il problema, rinominandone uno. Quando i due provengono da marketplace diversi, può farlo un manutentore di uno qualsiasi dei due.

`This plugin uses a source type your Claude Code version does not support`

Hai installato un plugin la cui voce nel marketplace utilizza un tipo di sorgente che questa versione di Claude Code non può recuperare, e Claude Code si è fermato con questo messaggio e Update Claude Code and try again.

Aggiorna Claude Code, quindi riprova l'installazione. I tipi di sorgente sono descritti nel riferimento del marketplace.

`Plugin archive integrity check failed`

Hai installato un plugin distribuito come archivio zip, e Claude Code l'ha rifiutato con questa riga e The archive was not installed. La voce del plugin nel marketplace utilizza una sorgente archive con un pin sha256, e il digest del file scaricato non corrisponde al pin.

Il messaggio completo è simile a questo:

Plugin archive integrity check failed for https://artifacts.example.com/claude-plugins/my-plugin.zip: expected sha256 6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1, got ac52220c0914ef8ca6a602e4a7362f88d30fb021110f72a6d15b68c3fe7df2b7. The archive was not installed. Verify the sha256 in the marketplace entry, or that the URL serves the intended file.

La soluzione è diversa per chi pubblica e per chi installa:

• Pubblichi il plugin: ricalcola il digest del file esatto servito dall'URL e aggiorna lo sha256 nella voce del marketplace. Usa shasum -a 256 my-plugin.zip, oppure Get-FileHash -Algorithm SHA256 my-plugin.zip in PowerShell
• Installi il plugin: esegui /plugin marketplace update <name> in una sessione per aggiornare il catalogo nel caso in cui la voce sia stata corretta, quindi riprova l'installazione. Se i digest continuano a non corrispondere dopo l'aggiornamento, chiedi al proprietario del marketplace quale file ha fissato prima di installare

`An npm plugin source must name a registry package`

Un plugin la cui voce nel marketplace usa una sorgente npm non è riuscito a installarsi, aggiornarsi o caricarsi, e il messaggio include questa frase. Claude Code ha controllato il valore package della voce prima di recuperare qualsiasi cosa e l'ha rifiutato. Il messaggio indica il valore e il motivo:

"github:acme/formatter" was not installed: it is not an http or https link. An npm plugin source must name a registry package (name or name@version) or link to a tarball file. For a plugin in a git repository, use a "github", "url" or "git-subdir" source.

La voce deve essere modificata dal proprietario del marketplace:

• Se sei tu: cambia package in un valore accettato dal riferimento alla sorgente npm per i plugin, oppure passa la voce a una sorgente github, url o git-subdir
• Se non sei tu: segnala il messaggio al proprietario del marketplace

`Marketplace "" is registered from an untrusted source`

Un marketplace che avevi aggiunto in precedenza ha smesso di caricarsi, e così anche i suoi plugin. Questa riga appare nella scheda Errors di /plugin o al successivo aggiornamento.

Il marketplace è registrato con un nome riservato ai marketplace ufficiali di Anthropic, ma la sua sorgente registrata non è un repository GitHub anthropics. I nomi riservati vengono ricontrollati ogni volta che un marketplace si carica o si aggiorna, quindi il marketplace e i plugin installati da esso smettono di caricarsi.

Il messaggio completo indica il nome riservato e la soluzione:

Marketplace "claude-community" is registered from an untrusted source: The name 'claude-community' is reserved for official Anthropic marketplaces. Only repositories from 'github.com/anthropics/' can use this name. To fix it, remove the marketplace and re-add it from the official source.

La soluzione è diversa per gli utenti e per chi pubblica:

• Usi il marketplace: nella shell, esegui claude plugin marketplace remove <name>, quindi aggiungi di nuovo il marketplace dal repository ufficiale github.com/anthropics
• Pubblichi un marketplace di terze parti che usava il nome prima che diventasse riservato: rinominalo e chiedi agli utenti di aggiungerlo di nuovo dalla tua sorgente

Prima della v2.1.205, Claude Code controllava il nome solo quando aggiungevi il marketplace, quindi una voce registrata prima che il suo nome diventasse riservato continuava a caricarsi.

`Marketplace "" is added but ignored`

Il marketplace ha una voce in ~/.claude/plugins/known_marketplaces.json, ma la voce non ha superato un controllo che Claude Code esegue ogni volta che legge quel file, quindi il marketplace e i plugin installati da esso smettono di caricarsi. Nella shell, claude plugin list segnala ogni plugin interessato con una riga che indica il motivo e la soluzione:

Marketplace team-tools is added but ignored. Its location is on a network drive, has "." or ".." in its path, or couldn't be checked. Re-add the marketplace (one added from a folder or file must be re-added from a copy on this computer), or, to trust a folder on a network drive, declare it under extraKnownMarketplaces in user or managed settings.

In una sessione, la scheda Errors di /plugin mette il nome del marketplace tra virgolette, termina la riga dopo il motivo e mostra la soluzione nella riga sottostante.

La frase dopo is added but ignored indica il controllo che la voce non ha superato:

• Its location is on a network drive, has "." or ".." in its path, or couldn't be checked, o la stessa frase riferita a The folder or file it was added from: la directory del marketplace, o il percorso locale da cui è stato aggiunto, si trova in una posizione di rete, ha un segmento . o .. nel percorso, oppure non è stato possibile controllarla
• Its git URL can't be used: <reason> o Its URL can't be read as an https:// or http:// address: l'URL della sorgente registrato nella voce è uno da cui Claude Code si rifiuta di clonare o recuperare
• Its source doesn't match its extraKnownMarketplaces entry in user or managed settings: la voce non corrisponde alla dichiarazione extraKnownMarketplaces con lo stesso nome

Quando dopo is added but ignored compare (see the debug log) al posto di un motivo, Claude Code rifiuta il nome del marketplace, ad esempio un'altra grafia di un nome riservato. Il log di debug indica la voce.

Cosa fare:

• Segui la soluzione indicata nel messaggio. Nella shell, esegui claude plugin marketplace remove <name>, quindi aggiungi di nuovo il marketplace da una sorgente supportata o da un percorso locale e reinstalla i suoi plugin, che il comando di rimozione disinstalla. Il comando di rimozione funziona su una voce ignorata
• Per mantenere un marketplace in una posizione di rete, dichiaralo sotto extraKnownMarketplaces nelle tue impostazioni utente o gestite; una dichiarazione in .claude/settings.json o .claude/settings.local.json di un repository non conta
• Per una sorgente che differisce dalla sua dichiarazione nelle impostazioni, aggiungi di nuovo il marketplace dalla sorgente dichiarata o modifica la dichiarazione. claude plugin marketplace add rifiuta la stessa discrepanza; consulta la voce Cannot add marketplace corrispondente
• Per un nome rifiutato, rimuovi il marketplace, usando il comando dopo Remove it: quando la riga ne indica uno; aggiungerlo di nuovo con lo stesso nome viene rifiutato di nuovo

Prima della v2.1.286, qualunque fosse il motivo, claude plugin list segnalava un marketplace di questo tipo come Marketplace <name> not found, e la scheda Errors di /plugin lo segnalava come Marketplace "<name>" is registered but was refused (see the debug log). Il motivo appariva solo nel log di debug. Nella v2.1.286, le frasi del motivo e della soluzione usavano una formulazione diversa, come Its recorded location is network-shaped or unclassifiable (never probed).

`Plugin has a corrupt manifest file` or `has an invalid manifest file`

Claude Code ha recuperato il plugin, ma poi non è riuscito a leggere il suo .claude-plugin/plugin.json. Nella shell, il <name> in questa riga può essere il nome di una directory temporanea; il prefisso Failed to install plugin "<name>@<marketplace>" riporta il nome reale del plugin. La formulazione indica quale controllo non è stato superato:

• corrupt manifest file, seguito da JSON parse error:: il file non è JSON valido
• invalid manifest file, seguito da Validation errors:: il file viene analizzato ma non rispetta lo schema, ad esempio name: Invalid input per un campo obbligatorio mancante

claude plugin install segnala entrambi i casi come Failed to install plugin "<name>@<marketplace>": ed esce con codice 1.

L'autore del plugin deve correggere il file, e fino ad allora il plugin non può essere installato:

• Se sei tu: esegui claude plugin validate <plugin-directory> nella shell per vedere lo stesso errore con il percorso problematico, quindi correggi il file
• Se non sei tu: segnala il messaggio al proprietario del marketplace

`Plugin directory not found at path: `

La scheda Errors in /plugin mostra questo messaggio per un plugin abilitato che il suo marketplace elenca tramite un percorso relativo, come ./plugins/my-plugin, quando non esiste alcuna directory in quel percorso all'interno del marketplace. Se gestisci il marketplace, correggi il percorso source della voce o ripristina la cartella. Altrimenti, segnala il messaggio al proprietario del marketplace.

Marketplace directory not found at path: <path> significa invece che manca la directory del marketplace stesso. Per un marketplace che hai aggiunto da un percorso locale, quella directory è stata spostata o eliminata. Ripristinala, oppure rimuovi il marketplace e aggiungilo di nuovo dalla sua nuova posizione.

`No plugins available` or `No marketplaces configured`

Hai aperto /plugin e la scheda Discover è vuota, oppure claude plugin marketplace list ha stampato No marketplaces configured.

Nessun marketplace è registrato, quindi non c'è alcun catalogo da mostrare. In una sessione, aggiungi il marketplace ufficiale, anthropics/claude-plugins-official:

/plugin marketplace add anthropics/claude-plugins-official

Claude Code stampa Successfully added marketplace: claude-plugins-official e Discover elenca i suoi plugin. La pagina Anthropic marketplaces elenca gli altri marketplace che puoi aggiungere.

`Marketplace "" is already added from a different source`

Hai confermato l'aggiunta di un marketplace tramite /plugin install <plugin> --marketplace <source>, e il catalogo che Claude Code ha recuperato da quella sorgente ha lo stesso nome di un marketplace che hai già aggiunto da una sorgente diversa. Claude Code mantiene il marketplace esistente invece di sostituirlo, e il plugin non viene installato.

Il messaggio completo è simile a questo:

Marketplace "acme-tools" is already added from a different source (github:acme/plugins). To use this source instead, remove that marketplace first with /plugin marketplace remove acme-tools.

Scegli quale sorgente vuoi:

• Il marketplace che hai già aggiunto: installa da esso indicandone il nome con /plugin install <plugin>@<name>
• La nuova sorgente: esegui /plugin marketplace remove <name>, quindi riprova l'installazione

`Cannot add marketplace "": its source doesn't match its extraKnownMarketplaces entry in user or managed settings`

Hai aggiunto un marketplace, e il name nel suo marketplace.json ha già una voce extraKnownMarketplaces nelle tue impostazioni utente o nelle impostazioni gestite. La sorgente che hai fornito è diversa da quella indicata in quella voce, quindi Claude Code rifiuta l'aggiunta e non registra nulla.

Due sorgenti corrispondono quando hanno lo stesso tipo e lo stesso valore in ogni campo. Una voce che imposta un ref che non hai passato conta come diversa. Anche una voce github conta come diversa quando hai fornito il repository come URL https://github.com/, perché Claude Code registra quell'URL come sorgente git. Procedi in uno di questi modi:

• Usa la sorgente dichiarata: Claude Code registra autonomamente i marketplace dichiarati nelle impostazioni, quindi esegui prima /plugin marketplace list in una sessione. Se l'elenco mostra il nome, il marketplace è già registrato e non c'è nulla da aggiungere.

  Se l'elenco non lo mostra, aggiungilo digitando la sorgente nel modo in cui la scrive la voce. Per una voce il cui oggetto source è { "source": "github", "repo": "acme-corp/claude-plugins", "ref": "v1.2.0" }, esegui questo:

  /plugin marketplace add acme-corp/claude-plugins#v1.2.0
  

• Usa la nuova sorgente: modifica o rimuovi la voce extraKnownMarketplaces, quindi aggiungi di nuovo il marketplace. Se sono le impostazioni gestite a dichiararla, chiedi al tuo amministratore

Prima della v2.1.287, il messaggio recitava Cannot add marketplace "<name>": its network source differs from the one declared for it in settings (kind, target, or a fetch-shaping field such as headers / ref / path / sparsePaths).

`Failed to install: ()`

Hai selezionato dei plugin da installare nel menu /plugin, nessuno di essi è stato installato, e il menu si è chiuso con questo riepilogo di ciò che non è andato a buon fine.

Alcuni motivi, come l'output di git dopo un clone non riuscito, mostrano solo la prima riga. Quando un motivo di questo tipo è stato abbreviato, il riepilogo termina con Installing a plugin from its details (Enter) in /plugin shows its full error.

Cosa fare dipende dal fatto che il riepilogo abbia abbreviato o meno il motivo:

• Correggi ciò che indica il motivo tra parentesi
• Quando il motivo è stato abbreviato, esegui /plugin, seleziona il plugin nella scheda Discover e premi Enter per installarlo dai suoi dettagli. Se l'installazione non riesce lì, la vista dei dettagli mostra l'errore completo

`Could not move the new copy of this plugin version into `

Quando installi un plugin, Claude Code scarica una nuova copia dei suoi file e la sposta nella cartella di quella versione nella cache dei plugin. Questo messaggio significa che lo spostamento non è riuscito, di solito perché un altro programma stava usando la cartella mentre l'installazione era in corso. Il codice del file system appare tra parentesi:

Could not move the new copy of this plugin version into /home/user/.claude/plugins/cache/acme-tools/formatter/1.2.0: the new copy or the version folder stayed busy while the install ran (ENOTEMPTY) — usually a scanner still reading the freshly downloaded files, another program using that folder, or another process re-creating it. The previously installed copy was moved back. Run the install again once other Claude Code sessions or programs using that folder have finished.

Il messaggio indica cosa è successo alla copia installata in precedenza, il che ti dice se il plugin funziona ancora:

• The previously installed copy was moved back: la versione che avevi è ancora installata
• had to be removed first, was not moved back o could not be moved back: quella versione del plugin non è installata finché un'installazione non va a buon fine
• Nessuna frase di questo tipo: non c'era una copia precedente, quindi la versione non è ancora installata

Su Windows, quando un altro programma tiene occupata la copia installata stessa, il messaggio dice invece che quella copia could not be replaced e che It was not replaced and the new copy was discarded, quindi la versione che avevi è ancora installata.

Un elenco Left on disk indica le cartelle messe da parte all'interno della cache. Un'installazione successiva di quella versione o una pulizia della cache dei plugin le rimuove, quindi non devi eliminarle.

Per correggere l'installazione:

• Chiudi le altre sessioni di Claude Code, gli editor e i terminali che usano la cartella del plugin in ~/.claude/plugins/cache, quindi esegui di nuovo l'installazione
• Quando il messaggio dice di controllare i permessi della cartella della cache dei plugin, ripristina il tuo permesso di scrittura sulla cartella indicata e libera spazio su disco, quindi esegui di nuovo l'installazione

Dependency errors

Un plugin che dichiara delle dipendenze può non riuscire a installarsi, oppure installarsi e restare disabilitato, quando una dipendenza non può essere soddisfatta. Il messaggio ti raggiunge al momento dell'installazione o al momento del caricamento:

• Durante l'installazione: il rifiuto viene restituito come messaggio di errore dell'installazione
• Quando il plugin si carica: il problema appare in claude plugin list e nella scheda Errors di /plugin, e Claude Code mantiene disabilitato il plugin interessato finché non risolvi il problema

La tabella elenca ogni messaggio e la relativa soluzione. Per dichiarare le dipendenze come autore, consulta Plugin dependencies.

Per visualizzarli a livello di programmazione, esegui claude plugin list --json nella shell. I plugin con problemi hanno un campo errors con i messaggi e un campo errorDetails con un type per ciascuno: le prime due righe corrispondono a dependency-unsatisfied e la terza a dependency-version-unsatisfied.

Plugin installed but not working

L'installazione è riuscita, ma le skills, gli hooks o i server del plugin non stanno facendo nulla. Iniziare con Plugin doesn't appear or its skills don't show up, che dice dove Claude Code segnala ciò che ha caricato, quindi abbinare il messaggio.

Plugin doesn't appear or its skills don't show up

È stato installato un plugin e è stato digitato / aspettandosi le sue skills, oppure è stato chiesto a Claude di usarlo e non è successo nulla.

Controllare lo stato del plugin prima di cambiare qualcosa:

Se il plugin si carica senza errore e le sue skills non appaiono ancora, il passo successivo differisce per il proprio plugin e per quello di qualcun altro:

• Un plugin che si sta costruendo: vedere Plugin loads but its skills are missing
• Un plugin che qualcun altro ha pubblicato: aprire Installed in /plugin e aprire il riquadro dei dettagli del plugin, che elenca ciò che il plugin contiene. Un plugin che non elenca skills lì non ne ha da offrire quando si digita /

`Run /reload-plugins to activate.`

Il riepilogo dell'installazione in /plugin è terminato con Run /reload-plugins to activate. invece di Plugin is now active.

Claude Code non ha attivato il plugin durante l'installazione, perché attivarlo avrebbe invalidato la cache del prompt o perché il tentativo di attivazione è fallito.

Non è necessario digitare il comando. Il pannello si chiude e Claude Code esegue /reload-plugins per voi, oppure lo mette in coda fino a quando la risposta che sta trasmettendo non finisce.

Leggere ciò che quel ricaricamento stampa:

• Reloaded: con conteggi di plugin, skills, agent, hooks e server: il plugin è ora attivo. Quando qualcosa non è riuscito a caricarsi, la riga aggiunge N errors during load. Run /plugin for details.
• This reload changes MCP tools (...) — your next message will re-read the whole conversation instead of using the cache. Run /reload-plugins --force to apply.: il ricaricamento aggiungerebbe o rimuoverebbe un server MCP del plugin o lo strumento LSP e invaliderebbe la cache del prompt. Per il caso LSP la riga inizia con This reload adds the LSP tool o This reload removes the LSP tool. Eseguirlo con --force per attivare il plugin comunque, oppure avviare una nuova sessione

Prima della v2.1.268, un'installazione che non è stata attivata durante l'installazione è rimasta in sospeso fino a quando non è stato eseguito /reload-plugins da soli.

Prima della v2.1.246, il conteggio delle skills in quel riepilogo includeva solo le voci commands/ di un plugin, quindi un ricaricamento potrebbe caricare le skills SKILL.md di un plugin e comunque segnalare 0 skills.

`The packages it lists are not installed` o `were not installed, because ...`

/plugin e claude plugin list mostrano una di queste note su un plugin la cui installazione delle dipendenze non ha lasciato alcuna directory node_modules. Il plugin si carica, ma le parti che richiedono i pacchetti mancanti potrebbero non funzionare.

• are not installed: l'installazione può essere eseguita per questo plugin ma non è stata completata, ad esempio perché non è riuscita o è scaduta. Per riprovare l'installazione, esegui nella tua shell il comando claude plugin update indicato dalla nota, oppure aggiorna il plugin da /plugin

  claude plugin update formatter@my-marketplace
  

  Se il nuovo tentativo non riesce, l'output ne indica la causa. Finché è impostata CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, claude plugin update e /plugin saltano il nuovo tentativo e segnalano che il plugin è all'ultima versione.

• were not installed, because ...: l'installazione non può essere eseguita per questo plugin e la nota ne indica il motivo, ad esempio un lockfile di Yarn, pnpm o bun.lockb, oppure un lockfile il cui gestore di pacchetti non è installato su questo computer. Aggiornare il plugin non installa i pacchetti finché quel motivo persiste. Se il motivo è il lockfile, deve sostituirlo l'autore del plugin. Se manca un gestore di pacchetti, installalo, quindi aggiorna il plugin

`Plugin "" not cached at `

La scheda Errors mostra questa riga con la guida Run /plugin to refresh the plugin cache. Claude Code ha un record di installazione per il plugin, ma la directory a cui il record punta è mancante, ad esempio dopo aver cancellato la cache.

Reinstallare il plugin dalla shell. claude plugin install <name>@<marketplace> scarica di nuovo un plugin la cui directory di installazione è mancante anche se il suo record esiste:

claude plugin install <name>@<marketplace>

Quindi eseguire /reload-plugins nella sessione. La voce della scheda Errors scompare e il plugin è di nuovo sotto Installed.

`installed_plugins.json holds a record under "" that this version of Claude Code cannot read`

Il messaggio appare in queste forme:

• claude plugin list: lo stampa come Note:
• claude plugin install, uninstall, e update: rifiutano con Plugin "<name>" was not installed:, Plugin "<name>" was not uninstalled:, o Plugin "<name>" was not updated:, seguito dallo stesso testo
• --json su uno di questi tre comandi: la riga del risultato contiene lo stesso message e failureCode: "install_records_unreadable"
• Diversi record di questo tipo: il messaggio legge holds records under
• L'intero file dichiara un formato che questa versione non conosce: il messaggio legge installed_plugins.json is in a format (version <N>) that this version of Claude Code does not know al suo posto

Il record denominato in installed_plugins.json è JSON valido sotto un id plugin valido, ma i suoi campi non si analizzano per questa versione. Molto probabilmente un'altra versione di Claude Code l'ha scritto, forse una più recente.

Mentre il record è lì, questa versione non riscrive il file, quindi il record non viene perso.

Prendere le opzioni del messaggio in ordine:

1. Aggiornare Claude Code con claude update.
2. Se non è possibile aggiornare, disinstallare il plugin denominato con la versione di Claude Code che ha scritto il record.
3. Se nessuno dei due aiuta, eliminare il record da installed_plugins.json manualmente, quindi riavviare Claude Code o eseguire /reload-plugins.

`installed_plugins.json could not be read and was rebuilt`

claude plugin list stampa questa nota, con il percorso di un file conservato denominato installed_plugins.unreadable.<date>.<hash>.kept, finché quel file si trova accanto a installed_plugins.json.

Un installed_plugins.json che non è JSON valido, o non è un elenco di plugin, non può dire cosa è stato installato.

Aprire il file .kept per vedere cosa il vecchio file ha registrato e reinstallare i plugin mancanti. Claude Code non legge mai il file di nuovo e il file invecchia secondo la pianificazione cleanupPeriodDays.

`install records under names that no version of Claude Code can use were removed from installed_plugins.json`

claude plugin list stampa questa nota, con il percorso di una copia denominata installed_plugins.set-aside.<date>.<hash>.json, finché quella copia si trova accanto a installed_plugins.json. La nota termina con Nothing needs doing about these copies.

Un record in installed_plugins.json si trovava sotto una chiave che non è un id plugin valido, quindi nessuna versione di Claude Code può usarlo. Il resto del file si carica normalmente.

Claude Code copia i record inutilizzabili nel file .set-aside e li elimina dall'elenco. Claude Code non legge mai le copie di nuovo e le copie invecchiano secondo la pianificazione cleanupPeriodDays.

`Disabled in ~/.claude/settings.json but still loads`

È stato impostato un plugin su false in ~/.claude/settings.json e la sua riga in claude plugin list o /plugin mostra questo messaggio seguito dalla fonte che lo abilita, come — project settings enable it, which overrides your user setting. Un true in quella fonte con precedenza più alta sta sovrascrivendo l'impostazione dell'utente.

Per rinunciare a un plugin abilitato dal progetto sulla macchina, impostare l'id su false in .claude/settings.local.json, che ha precedenza più alta rispetto al file del progetto. Per le altre fonti che il messaggio può nominare, vedere Disabled in user settings but still loads.

Se claude plugin list invece contrassegna il plugin required by your org, nessun file di impostazioni è coinvolto: l'organizzazione contrassegna quel plugin sincronizzato come richiesto su claude.ai e si carica anche se è stato disabilitato in precedenza. Vedere Plugins synced from claude.ai.

`Plugin "" is enabled in project settings but isn't installed here`

La scheda Errors mostra questa riga per un plugin che il .claude/settings.json del progetto abilita, con la guida Run claude plugin install <name>@<marketplace> --scope project to install it for this project.

Le impostazioni di un repository possono abilitare un plugin per tutti coloro che lo aprono, ma non lo installano. Quando il plugin proviene da una fonte esterna come un repository GitHub o un pacchetto npm, Claude Code non lo scarica fino a quando non lo si installa da soli. Eseguire il comando dalla riga di guida nella shell, quindi ricaricare:

claude plugin install <name>@<marketplace> --scope project

Dopo aver eseguito /reload-plugins nella sessione, la voce della scheda Errors è scomparsa e il plugin è elencato sotto Installed.

Se l'organizzazione pre-installa i plugin, lo fa attraverso le impostazioni gestite al suo posto. Vedere Pre-install and require plugins.

`Failed to load hooks from ` and hooks that don't fire

Gli hooks di un plugin non vengono eseguiti, oppure uno blocca un'azione. O la scheda Errors mostra un fallimento di caricamento per loro, gli hooks si caricano e si vedono avvisi <Event> hook error o un errore di blocco nella trascrizione, oppure un hook si carica senza errore e non si attiva mai.

Hooks fail to load

La scheda Errors mostra uno di questi messaggi:

• Failed to load hooks from <path>: <reason>: hooks/hooks.json non è JSON valido o fallisce lo schema degli hooks. Il motivo nomina l'errore di analisi o convalida. Correggere il file. Per catturare un problema di sintassi JSON in hooks/hooks.json prima di pubblicare il plugin, eseguire claude plugin validate <plugin-directory> nella shell
• hooks path not found: <path>: il campo hooks del manifest nomina un file che non esiste in quel percorso relativo alla radice del plugin. Correggere il percorso o aggiungere il file

`hook error` notices in the transcript

Un avviso della forma ... hook error: Failed with non-blocking status code: <stderr> significa che l'hook è stato eseguito e il suo comando è fallito. Ad esempio, Stop hook error: Failed with non-blocking status code: /bin/sh: node: command not found significa che la shell che Claude Code ha generato non poteva trovare node. Installarlo o assicurarsi che sia su PATH del terminale da cui si avvia claude.

Se lo stderr mostra il percorso del plugin tagliato a uno spazio, il comando in forma shell dell'hook utilizza ${CLAUDE_PLUGIN_ROOT} al di fuori delle virgolette e il percorso di installazione contiene uno spazio. Avvolgere la variabile tra virgolette doppie o utilizzare exec form. Per trovare la variabile non quotata, eseguire claude plugin validate sulla directory del plugin e cercare il suo avviso di quotazione.

Per qualsiasi altro errore, eseguire il comando dell'hook da soli dalla directory del plugin per vedere l'output completo o catturare lo stderr completo con debug logging.

A plugin hook blocks a tool call or prompt

Un hook che esce con codice 2 blocca l'azione per cui è stato eseguito. Quando un hook di un plugin blocca in questo modo e il suo stderr è il messaggio di blocco, l'errore termina con This hook comes from the <plugin> plugin. in modo che si sappia quale plugin disabilitare o correggere. Prima della v2.1.281, l'errore non nominava il plugin.

Se quel messaggio mostra il percorso del plugin tagliato a uno spazio, applicare la correzione ${CLAUDE_PLUGIN_ROOT} non quotata.

Hook loads but never fires

Se un hook si carica senza errore ma non si attiva mai, controllare la sua definizione e quindi osservarlo in esecuzione:

`Invalid MCP server config for ""` and MCP servers that don't start

Un plugin raggruppa un server MCP e la scheda Errors mostra Invalid MCP server config for "<server>": <error> oppure il server è elencato ma /mcp non lo mostra mai connesso.

`Invalid MCP server config for "": `

La configurazione del server passa il controllo dello schema, ma Claude Code non può risolverla per questa sessione. Il testo dopo i due punti nomina la causa e decide la soluzione:

• Missing environment variables: <names>: impostare quelle variabili nella shell da cui si avvia Claude Code, quindi avviare una nuova sessione
• URL is unset or invalid: un'opzione ${user_config.*} che l'URL utilizza non è impostata. Eseguire /plugin configure <plugin> per impostarla
• has an invalid MCP url o headersHelper for MCP server '<server>' references ${user_config.*}: la configurazione del plugin stesso è in difetto. Correggere l'url o headersHelper nella configurazione MCP del plugin o segnalarlo all'autore del plugin se il plugin non è vostro. Il caso headersHelper ha la sua voce sotto plugin command references user_config

`Bundled MCP server "" was not started: it needs configuration`

Il plugin include il server come un MCPB bundle che dichiara user_config, e un'impostazione richiesta non ha un valore salvato ancora o un valore salvato fallisce la convalida propria del bundle, quindi Claude Code salta l'avvio del server. Il resto del plugin funziona.

Selezionare il plugin sulla scheda Installed di /plugin e scegliere Configure per fornire i valori. Dopo aver salvato, /plugin mostra Configuration saved. e si chiude, e Claude Code ricarica i plugin come descritto sotto Manage installed plugins. Il server si avvia una volta che quel ricaricamento si applica. Prima della v2.1.285, Claude Code saltava il server senza mostrare questa riga.

Server is configured but never connects

Eseguire /mcp per vedere lo stato del server. Quando il server è sano, /mcp lo elenca come connesso.

Per leggere l'errore che il server ha stampato durante l'avvio, eseguire claude --debug e aprire il log su ~/.claude/debug/<session-id>.txt. Il flag --debug non stampa al terminale.

Una voce del server in .mcp.json che fallisce lo schema non appare nella scheda Errors. Claude Code scarta quel server e registra Invalid MCP server config for <server> in <path> solo in quel log di debug. Per trovare la voce senza caricare il plugin, eseguire claude plugin validate nella shell sulla directory del plugin, che la segnala come errore.

Prima della v2.1.281, claude plugin validate non controllava .mcp.json.

Server works with `--plugin-dir` but fails after install

Siete l'autore del plugin e il server si avvia quando si carica il plugin dalla sua directory di origine con --plugin-dir ma fallisce una volta che il plugin è installato.

Claude Code copia un plugin installato nella sua cache, quindi un percorso che funziona solo dalla directory di origine si interrompe. Scrivere i percorsi all'interno del plugin con ${CLAUDE_PLUGIN_ROOT}.

Per i percorsi che raggiungono al di fuori della directory del plugin, vedere Files the plugin references outside its directory aren't found.

Language server doesn't start, uses too much memory, or reports wrong diagnostics

È stato installato un code intelligence plugin e Claude non sta vedendo diagnostiche, oppure il language server sta utilizzando troppa memoria o segnalando errori che non sono reali.

Language server doesn't start

Il plugin si connette a un binario del language server che si installa separatamente e Claude Code lo genera per nome dalla PATH.

La scheda Errors di /plugin mostra il fallimento con il suo motivo, come Executable not found in $PATH: "<binary>" e claude --debug lo registra come LSP server <name> failed to start: <reason>.

Installare il binario e confermare che sia su PATH del terminale da cui si avvia claude, ad esempio con which typescript-language-server. Quindi avviare una nuova sessione.

Language server uses too much memory

I language server come rust-analyzer e pyright indicizzano l'intero progetto. Disabilitare il plugin con /plugin disable <plugin> in una sessione e affidarsi agli strumenti di ricerca integrati di Claude al suo posto.

False positive diagnostics in a monorepo

Un language server che non è configurato per lo spazio di lavoro può segnalare importazioni non risolte per i pacchetti interni. Non c'è nulla da correggere dal lato di Claude Code e le diagnostiche non impediscono a Claude di modificare il codice.

Creare un plugin

Stai sviluppando un plugin e lo stai caricando con --plugin-dir o lo stai installando da un marketplace locale. Queste voci coprono i guasti che incontri durante lo sviluppo di un plugin. Per eseguire i controlli dopo ogni modifica, vedi Test and debug.

Due guasti che raggiungono anche gli utenti di un plugin hanno le loro voci sotto Plugin installed but not working:

• Un hook che non si attiva: vedi hooks that don't fire
• Un server MCP che non si avvia: vedi MCP servers that don't start

`commands path not found: `

La scheda Errors mostra commands path not found: <absolute path> con la guida Check that the path in your manifest or marketplace config is correct. Lo stesso messaggio appare per skills, agents e hooks.

Claude Code ha risolto un percorso dal tuo plugin.json o dalla voce del marketplace rispetto alla radice del plugin e non ha trovato nulla lì. Il percorso nel messaggio è il percorso assoluto che ha controllato, quindi confrontalo con quello su disco. Correggi il percorso o crea la directory, quindi esegui /reload-plugins.

I percorsi nel manifest sono relativi alla radice del plugin e iniziano con ./. Un percorso che si risolve al di fuori della radice del plugin viene segnalato come <component> path escapes plugin directory e viene eliminato.

`--plugin-dir` in una radice del marketplace non carica i plugin sotto `plugins/`

Hai avviato claude --plugin-dir <path> e non vedi errori, ma le skill, gli agenti e gli hook del plugin non sono lì.

--plugin-dir accetta la directory radice del plugin, quella che contiene .claude-plugin/plugin.json e le directory dei componenti come skills/. Se la punti a una radice del marketplace, Claude Code non legge marketplace.json, quindi un plugin sotto plugins/ non si carica e non vedi errori. Prima della v2.1.281, Claude Code caricava una radice del marketplace come un plugin vuoto denominato dopo quella directory. Punta il flag alla directory del plugin stesso:

claude --plugin-dir ./my-marketplace/plugins/my-plugin

Quindi apri Installed in /plugin, dove il riquadro dei dettagli del plugin elenca i suoi componenti.

I file a cui il plugin fa riferimento al di fuori della sua directory non vengono trovati

Un plugin funziona dalla sua directory di origine con --plugin-dir ma fallisce dopo l'installazione, con errori su un percorso come ../shared-utils.

Claude Code copia un plugin installato nella sua cache e lo carica da lì, quindi un percorso che raggiunge al di fuori della directory del plugin stesso non punta a nulla nella cache. Sposta i file condivisi all'interno della directory del plugin o fai riferimento ad essi tramite un collegamento simbolico al suo interno. Per sapere dove si trova la cache e come si risolvono i percorsi, vedi Find plugins on disk.

`${CLAUDE_PLUGIN_ROOT}` mostra barre oblique in avanti su Windows

Su Windows, un hook del plugin riceve ${CLAUDE_PLUGIN_ROOT} come C:/Users/you/... anziché C:\Users\you\... e uno script che si aspettava barre oblique inverse si interrompe.

Claude Code esegue gli hook in forma shell attraverso Git Bash su Windows e sostituisce la radice del plugin nella forma Win32 con barre oblique in avanti di proposito. I builtin di Bash, gli strumenti MSYS e i binari Windows nativi accettano tutti quella forma.

Se il tuo script ha bisogno di barre oblique inverse, passa l'hook a una delle forme che mantengono i percorsi nativi, descritte sotto exec form and shell form:

• Un hook in forma exec, che genera il processo direttamente con un array args
• Un hook con "shell": "powershell"

Il plugin si carica ma le sue skill sono mancanti

Il tuo plugin è elencato sotto Installed senza errori, ma le sue skill non vengono offerte quando digiti /.

Le skill si caricano da skills/ alla radice del plugin e i comandi da commands/ alla radice del plugin. Solo plugin.json appartiene a .claude-plugin/ e una directory skills/ all'interno di .claude-plugin/ non viene scansionata. Sposta le directory alla radice del plugin ed esegui /reload-plugins. Successivamente, il riquadro dei dettagli del plugin in /plugin elenca le skill e digitando / le offre.

Ogni skill è una directory contenente SKILL.md. Una voce skills nel manifest che punta a un file SKILL.md anziché alla sua directory viene segnalata come path is a file; skills entries must be directories containing SKILL.md.

La skill si carica ma Claude non invoca mai la skill

La skill del tuo plugin viene eseguita quando digiti il suo comando /<plugin>:<skill>, ma Claude non la invoca mai in risposta a una richiesta semplice.

Controlla queste cause in ordine:

• La skill imposta disable-model-invocation: true: con quel campo impostato, solo tu puoi invocare la skill. La skill del template in Create your first plugin lo imposta. Rimuovi la riga da una skill che vuoi che Claude invochi da solo. Control who invokes a skill copre il campo
• La descrizione non corrisponde a come le persone chiedono: lavora attraverso i controlli in Skill not triggering
• La descrizione è troncata: quando molte skill sono installate, Claude Code accorcia le descrizioni per adattarsi al budget dei caratteri dell'elenco, che può eliminare le parole chiave di cui Claude ha bisogno per abbinare una richiesta. Vedi Skill descriptions are cut short

Per misurare quanto spesso la skill si attiva su prompt realistici anziché controllare uno alla volta, scrivi un caso eval con un grader tool_used: Skill ed eseguilo con claude plugin eval dopo ogni modifica della descrizione.

` is not a plugin or skill folder` da `claude plugin eval init`

Hai eseguito claude plugin eval init da una directory che non è la radice di un plugin, come la tua directory home o la radice di un repository che mantiene il plugin in una sottodirectory. init scrive la suite nella directory di lavoro, quindi si ferma invece di creare una directory evals/ che il plugin non vedrebbe mai.

Cambia alla radice del plugin, la directory che contiene .claude-plugin/plugin.json o il SKILL.md della skill, ed esegui di nuovo il comando. Per impalcare la suite da qualche altra parte di proposito, passa --eval-dir. Vedi Test plugins with evals.

La finestra di dialogo `userConfig` non appare mai

Il tuo plugin dichiara opzioni userConfig, ma nessuna finestra di dialogo di configurazione appare quando lo installi.

Se l'installazione chiede i valori dipende da dove lo esegui:

• /plugin install in una sessione, o la scheda Discover in /plugin: la finestra di dialogo fa parte di questa installazione interattiva
• La finestra di dialogo Manage plugins dell'estensione VS Code: chiede le opzioni non impostate come un modulo dopo l'installazione. Prima della v2.1.285, l'installazione lì non mostrava alcun modulo di opzioni, quindi imposta i valori da una sessione di terminale con /plugin configure <plugin>@<marketplace>
• claude plugin install nella tua shell: non chiede mai i valori userConfig. Salva tutti i valori --config KEY=VALUE che passi e quando le opzioni rimangono non impostate stampa N userConfig options not yet set — run /plugin configure <plugin>@<marketplace> in Claude Code, or pass --config KEY=VALUE. Quando una qualsiasi delle opzioni non impostate è obbligatoria, (M required) segue not yet set.

Se hai installato dalla shell, passa i valori con --config, un flag per opzione:

claude plugin install my-plugin@my-marketplace --config api_url=https://example.com

Quando ogni opzione è impostata, l'output dell'installazione non contiene alcuna riga not yet set.

Per aprire la finestra di dialogo successivamente, esegui /plugin configure my-plugin@my-marketplace in una sessione. Dalla shell, claude plugin configure mostra quali opzioni sono ancora non impostate e salva i valori inviati su stdin. Richiede Claude Code v2.1.285 o successivo.

Se passi una chiave --config che il manifest non dichiara, il plugin si installa comunque e il comando stampa ⚠ Installed, but --config not applied: --config key "<key>" isn't declared in this plugin's userConfig. seguito dalle chiavi che il plugin dichiara.

Per un plugin che spedisce un file bundle MCPB che dichiara il suo user_config, il messaggio legge isn't declared in this plugin's userConfig or by its bundled MCP servers. invece, e le chiavi note includono le chiavi di quel server, scritte <server>.<key>. Un bundle che il manifest riferisce tramite URL non viene letto al momento dell'installazione, quindi le sue chiavi non sono elencate e il messaggio dice di configurarlo in /plugin. L'impostazione delle chiavi <server>.<key> richiede Claude Code v2.1.285 o successivo.

`claude plugin validate` segnala errori

Hai eseguito claude plugin validate <path>, o /plugin validate <path> in una sessione, e ha stampato Found N errors e Validation failed, quindi è uscito con codice 1.

Il validatore legge il manifest nel percorso che fornisci: .claude-plugin/plugin.json per una directory di plugin, o .claude-plugin/marketplace.json per una directory di marketplace. Per un marketplace, antepone i problemi nel manifest proprio di una voce con l'indice della voce, come plugins[1] plugin.json → json: ....

La tabella copre i messaggi che fermano la convalida e due avvisi, No frontmatter block found e Unknown field '<key>', che la fermano solo quando passi --strict. Altri avvisi, come una descrizione mancante, non sono elencati.

Esegui il comando di nuovo dopo ogni correzione finché non stampa errori.

I campi plugin.json sono nel manifest reference e i messaggi a livello di marketplace sono sotto Marketplace validation errors.

`Plugin has conflicting manifests`

Il plugin non si carica con Plugin <name> has conflicting manifests: both plugin.json and marketplace entry specify components.

Il plugin ha il suo plugin.json e la sua voce del marketplace imposta strict: false mentre dichiara anche uno qualsiasi di commands, agents, skills, hooks, outputStyles o themes. Rimuovi quei campi dalla voce o imposta strict: true nella voce in modo che Claude Code li aggiunga a plugin.json. Vedi Strict mode.

`Warning: No commands found in plugin custom directory`

Quando il plugin si carica, il log claude --debug in ~/.claude/debug/<session-id>.txt registra Warning: No commands found in plugin <name> custom directory: <path>. Expected .md files or SKILL.md in subdirectories. Nulla appare nella sessione o nella scheda Errors.

Il percorso commands nel manifest esiste ma non contiene file .md e nessun SKILL.md in una sottodirectory. Aggiungi i file di comando o rimuovi il percorso dal manifest.

Host a marketplace

Si pubblica un marketplace e un utente segnala un errore o la propria convalida fallisce. Queste voci sono per il proprietario del marketplace.

Plugins with relative paths fail in URL-based marketplaces

Gli utenti hanno aggiunto il marketplace con un URL https://example.com/marketplace.json. Le installazioni di plugin la cui source è un percorso relativo, come ./plugins/my-plugin, falliscono con its marketplace entry path does not stay inside the marketplace directory. I plugin già installati non si caricano con Plugin source path refused. Entrambi i messaggi hanno una voce di riferimento degli errori.

Quando un utente aggiunge un marketplace basato su URL, Claude Code scarica solo il file marketplace.json stesso. Non recupera i file dei plugin per percorso relativo da quel server, quindi un percorso relativo in una voce punta a una directory che non è mai stata scaricata. Dare a ogni voce una fonte che Claude Code può recuperare da solo, come un repository GitHub:

{ "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }

In alternativa, ospitare il marketplace in un repository git e dire agli utenti di aggiungerlo con l'URL del repository. Per una fonte git, Claude Code clona l'intero repository, quindi i percorsi relativi si risolvono. I tipi di fonte sono sul marketplace reference.

Marketplace validation errors

È stato eseguito claude plugin validate . dalla directory del marketplace e ha segnalato errori o avvisi sul file del marketplace stesso.

claude plugin validate convalida anche ogni voce la cui source è un percorso locale e avverte quando la version della voce non concorda con il manifest del plugin stesso.

La tabella elenca i messaggi a livello di marketplace. I messaggi a livello di voce sono i messaggi del plugin sotto claude plugin validate reports errors, prefissati con plugins[N] plugin.json →.

Prima della v2.1.247, un nome di marketplace contenente caratteri di controllo o di formattazione bidirezionale era segnalato solo come Marketplace name impersonates an official Anthropic/Claude marketplace.

Blocked by your organization

L'organizzazione distribuisce impostazioni gestite che limitano i plugin e un comando è stato rifiutato con un messaggio di politica. Queste voci nominano l'impostazione dietro ogni rifiuto in modo da sapere cosa chiedere all'amministratore. Per il lato amministratore, vedere Manage plugins for your organization.

`Marketplace source '' is blocked by enterprise policy`

È stato eseguito /plugin marketplace add, update o un'installazione e Claude Code ha rifiutato con questa riga. Per una fonte GitHub o git, l'host segue la fonte tra parentesi, come in 'github:owner/repo' (github.com).

L'amministratore ha impostato blockedMarketplaces o strictKnownMarketplaces nelle impostazioni gestite e questa fonte non è consentita. Chiedere all'amministratore di consentire la fonte o aggiungere una delle fonti consentite che il messaggio elenca.

Abbinare il resto del messaggio per vedere che tipo di politica ha bloccato la fonte:

• Allowed sources: <list>: il blocco proviene dall'elenco di autorizzazione strictKnownMarketplaces piuttosto che dall'elenco di blocco blockedMarketplaces
• No external marketplaces are allowed.: l'elenco di autorizzazione strictKnownMarketplaces è vuoto
• Un Tip: che lo shorthand assume github.com: l'elenco di autorizzazione consente un host git per nome host e lo shorthand owner/repo che è stato passato punta a github.com. Se il repository si trova sull'host interno, aggiungerlo di nuovo con il suo URL completo, come git@your-git-host.com:owner/repo.git

Un marketplace aggiunto prima che la politica diventasse più restrittiva smette di aggiornarsi anche perché la politica si applica ad ogni aggiornamento.

`Marketplace "" is not in the allowed marketplace list`

La scheda Errors mostra questa riga o Marketplace "<name>" is blocked by enterprise policy per un marketplace già registrato.

Le stesse impostazioni gestite che bloccano una marketplace source si applicano al momento del caricamento. strictKnownMarketplaces non include questo marketplace o blockedMarketplaces lo nomina, quindi Claude Code smette di caricarlo e i suoi plugin. Per la variante dell'elenco di autorizzazione, la riga di guida mostra le fonti consentite o Contact your administrator to configure allowed marketplace sources. Per la variante dell'elenco di blocco recita This marketplace source is explicitly blocked by your administrator.

`Plugin "" is blocked by your organization's policy and cannot be installed`

Un'installazione è stata rifiutata con questa riga, un'abilitazione con la stessa riga che termina cannot be enabled o un'installazione o aggiornamento con uno che nomina il motivo: Plugin "<name>" is from marketplace "<marketplace>", which is blocked by your organization's policy o Plugin "<name>" depends on "<dep>", which is blocked by your organization's policy.

Le impostazioni gestite bloccano questo plugin, il suo marketplace o una dipendenza di cui ha bisogno. Chiedere all'amministratore quale voce si applica. Un blocco di dipendenza significa che il plugin non può installarsi fino a quando il marketplace della dipendenza non è consentito.

`--plugin-dir is disabled by your organization's managed settings (disableSideloadFlags)`

È stato avviato claude con --plugin-dir, --plugin-url, --agents o --mcp-config. Claude Code è uscito con questo messaggio e Plugins, custom agents, and MCP servers can only be loaded from sources your administrator has approved.

L'amministratore ha impostato disableSideloadFlags nelle impostazioni gestite, che disattiva i flag che caricano plugin, agent e server da percorsi arbitrari. Caricare il plugin da un marketplace approvato al suo posto o chiedere all'amministratore di rimuovere l'impostazione.

Un messaggio correlato nella scheda Errors di /plugin è --plugin-dir copy of "<name>" ignored: plugin is locked by managed settings. Le impostazioni gestite abilitano o disabilitano quel plugin per nome e Claude Code ignora la copia --plugin-dir in modo che il flag non possa sovrascrivere la politica.

`Plugins from ~/.claude/skills/ are blocked by your organization's managed settings`

È stato eseguito claude plugin init o claude plugin enable e si è fermato con questa riga. Il messaggio nomina strictKnownMarketplaces or blockedMarketplaces e chiede all'amministratore di aggiungere {"source":"skills-dir"} a strictKnownMarketplaces o rimuoverlo da blockedMarketplaces.

La fonte skills-dir sta per i plugin che Claude Code carica dalla directory ~/.claude/skills/. Chiedere all'amministratore di fare il cambiamento che il messaggio nomina.

`Command-sourced plugins are disabled by your organization's managed settings`

È stato installato o aggiornato un plugin con una fonte command e si è fermato con questa riga e The plugin was not installed or updated and its command was not run.

L'amministratore ha impostato disableCommandPluginSources, quindi Claude Code rifiuta di eseguire il comando dichiarato dal marketplace che produce il plugin. L'impostazione di allowManagedHooksOnly da solo ha lo stesso effetto quando disableCommandPluginSources non è impostato. Chiedere all'amministratore se il plugin può essere pubblicato da un tipo di fonte che la politica consente.

`Marketplace '' is seed-managed`

È stato eseguito claude plugin marketplace update <name> e ha fallito con Marketplace '<name>' is seed-managed (<dir>) e un suggerimento di chiedere all'amministratore.

Un operatore ha pre-popolato questo marketplace tramite CLAUDE_CODE_PLUGIN_SEED_DIR e Claude Code tratta un marketplace seed-managed come di sola lettura. Un marketplace update in blocco lo salta e aggiorna gli altri.

Per modificare il contenuto del marketplace, chiedere alla persona che mantiene l'immagine seed di aggiornarlo. Per la procedura, vedere Seed containers and CI.

Next steps

• Plugin loading reference: perché gli ambiti, la cache e la precedenza si comportano in questo modo
• Plugin commands reference: flag, impostazioni predefinite, output e codici di uscita per i comandi claude plugin
• Install and manage plugins: i passaggi di installazione dall'inizio
• Manage plugins for your organization: risoluzione dei problemi dal lato della politica per gli amministratori