Risolvi i problemi di installazione e accesso

Correggi gli errori di comando non trovato, PATH, permessi, rete e autenticazione durante l'installazione o l'accesso a Claude Code.

Se l'installazione non riesce o non riesci ad accedere, trova il tuo errore di seguito. Per i problemi di runtime dopo che Claude Code è funzionante, vedi Risoluzione dei problemi. Per i problemi di configurazione come impostazioni non applicate o hook non attivati, vedi Debug della tua configurazione.

Trova il tuo errore

Abbina il messaggio di errore o il sintomo che stai vedendo a una soluzione:

Se il tuo problema non è elencato, esegui i controlli diagnostici di seguito per restringere la causa.

[!TIP]

Se preferisci saltare completamente il terminale, l'app Claude Code Desktop ti consente di installare e utilizzare Claude Code tramite un'interfaccia grafica. Scaricala per macOS o Windows e inizia a codificare senza alcuna configurazione da riga di comando. Su Linux, installa l'app con apt seguendo le istruzioni di installazione per Linux.

Esegui controlli diagnostici

Controlla la connettività di rete

Il programma di installazione scarica da downloads.claude.ai. Verifica di poterlo raggiungere:

[tab] macOS/Linux

curl -sI https://downloads.claude.ai/claude-code-releases/latest

[tab] Windows PowerShell

curl.exe -sI https://downloads.claude.ai/claude-code-releases/latest

PowerShell crea un alias di curl a Invoke-WebRequest, che rifiuta i flag -sI, quindi chiama curl.exe esplicitamente.

Hai raggiunto il server se la prima riga mostra uno stato 200. Vedrai HTTP/2 200 su macOS e Linux, e HTTP/1.1 200 OK da curl.exe incluso con Windows. Altri risultati indicano la causa:

• 403: solitamente un proxy o un filtro di rete che blocca l'host, o Claude Code non è disponibile nella tua regione
• 5xx: solitamente un problema temporaneo del servizio; attendi alcuni minuti e riprova

Se non vedi output, oppure il programma di installazione mostra Could not resolve host o un timeout di connessione, la connessione non è riuscita, quindi controlla queste cause:

• Firewall aziendali o proxy che bloccano downloads.claude.ai
• Restrizioni di rete regionali: prova una VPN o una rete alternativa
• Problemi TLS/SSL: vedi Errori di connessione TLS o SSL

Se sei dietro un proxy aziendale, imposta HTTPS_PROXY e HTTP_PROXY all'indirizzo del tuo proxy prima di installare. Chiedi al tuo team IT l'URL del proxy se non lo conosci, o controlla le impostazioni del proxy del tuo browser.

Questo esempio imposta entrambe le variabili proxy, quindi esegue il programma di installazione attraverso il tuo proxy:

[tab] macOS/Linux

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash

[tab] Windows PowerShell

$env:HTTP_PROXY = 'http://proxy.example.com:8080'
$env:HTTPS_PROXY = 'http://proxy.example.com:8080'
irm https://claude.ai/install.ps1 | iex

Verifica il tuo PATH

Se l'installazione è riuscita ma ricevi un errore command not found o not recognized quando esegui claude, la directory di installazione non è nel tuo PATH. La tua shell cerca i programmi nelle directory elencate in PATH, e il programma di installazione posiziona claude in ~/.local/bin/claude su macOS/Linux o %USERPROFILE%\.local\bin\claude.exe su Windows.

Il programma di installazione rileva questo caso e lo segnala sotto Setup notes: nel suo output: Native installation exists but ~/.local/bin is not in your PATH. su macOS e Linux, oppure Native installation exists but C:\Users\you\.local\bin is not in your PATH. su Windows. Insieme a quella nota stampa la correzione, ma non modifica il PATH da solo.

[!NOTE]

L'estensione VS Code non posiziona claude in questa posizione. Raggruppa una copia privata della CLI all'interno della directory dell'estensione per il suo pannello di chat e non la aggiunge a PATH. Se hai installato solo l'estensione, ~/.local/bin/claude non esisterà. Esegui l'installazione standalone per utilizzare claude da un terminale, quindi continua di seguito.

Per prima cosa controlla che il programma sia effettivamente presente, poi controlla se la sua cartella è nel tuo PATH. La correzione del PATH è permanente, quindi la applichi una sola volta. Scegli la scheda della tua piattaforma ed esegui lì i relativi comandi: nel tuo terminale su macOS e Linux, oppure in PowerShell o nel Prompt dei comandi su Windows.

[tab] macOS/Linux

Controlla che il programma di installazione abbia messo il programma al suo posto:

ls -la ~/.local/bin/claude

• No such file or directory: non c'è un'installazione nativa. Se non hai installato Claude Code in un altro modo, ad esempio con npm, Homebrew o un gestore di pacchetti Linux, installa Claude Code. Se lo hai installato in un altro modo, vedi Controlla le installazioni in conflitto.
• Un elenco per il file: il programma è presente. Controlla poi il tuo PATH.

Elenca le tue voci PATH e filtra per la cartella di installazione:

echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"

Se questo stampa /Users/you/.local/bin o /home/you/.local/bin, la directory è nel tuo PATH e puoi saltare a Controlla le installazioni in conflitto. Se non c'è output, aggiungila alla tua configurazione della shell con i due comandi per la tua shell. Il comando echo salva l'impostazione per ogni nuovo terminale, e source la applica alla finestra in cui ti trovi. Il comando echo non stampa nulla quando riesce.

Per Zsh, il default su macOS:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Per Bash su Linux, dove è il default sulla maggior parte delle distribuzioni:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Per Bash su macOS, aggiungi la riga a ~/.bash_profile invece. Terminal su macOS avvia Bash come shell di login, che ignora ~/.bashrc e legge solo il primo di ~/.bash_profile, ~/.bash_login, o ~/.profile che esiste. Se hai già un ~/.bash_login o ~/.profile e nessun ~/.bash_profile, metti la riga in quel file piuttosto che creare ~/.bash_profile:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bash_profile
source ~/.bash_profile

In alternativa, chiudi e riapri il tuo terminale.

Se il comando echo stampa permission denied, vedi permission denied quando aggiungi al tuo PATH.

Per altre shell come fish o Nushell, aggiungi ~/.local/bin al tuo PATH usando la sintassi di configurazione della tua shell, quindi riavvia il tuo terminale.

Verifica che la correzione abbia funzionato:

claude --version

Se claude non viene ancora trovato, controlla queste cause:

• Il terminale è precedente alla modifica: una finestra già aperta mantiene il suo vecchio PATH, e un terminale all'interno di un editor prende il suo PATH dall'editor. Apri una nuova finestra, oppure chiudi e riapri l'editor.
• La riga non è stata salvata: esegui grep -n '.local/bin' ~/.zshrc, usando il nome del file della tua shell. Se la riga è presente, la stampa con il suo numero di riga. Se non stampa nulla, esegui di nuovo i due comandi PATH.
• La riga è finita nel file di un'altra shell: esegui echo $0 per vedere la tua shell, quindi esegui i due comandi PATH per quella shell.

[tab] Windows PowerShell

Controlla che il programma di installazione abbia messo il programma al suo posto:

Test-Path "$env:USERPROFILE\.local\bin\claude.exe"

• False: non c'è un'installazione nativa. Se non hai installato Claude Code in un altro modo, ad esempio con npm o WinGet, installa Claude Code. Se lo hai installato in un altro modo, vedi Controlla le installazioni in conflitto.
• True: il programma è presente. Controlla poi il tuo PATH.

Elenca le tue voci PATH e filtra per la cartella di installazione:

$env:PATH -split ';' | Select-String '\.local\\bin'

Se questo stampa C:\Users\you\.local\bin, la directory è nel tuo PATH e puoi saltare a Controlla le installazioni in conflitto. Se non c'è output, aggiungi la directory di installazione al tuo User PATH:

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

Riavvia il tuo terminale affinché la modifica abbia effetto.

Verifica che la correzione abbia funzionato:

claude --version

Se claude non viene ancora trovato in un nuovo terminale, controlla queste cause:

• Il terminale viene eseguito all'interno di un editor: prende il suo PATH dall'editor, quindi chiudi e riapri l'editor.
• La modifica non è stata salvata: esegui [Environment]::GetEnvironmentVariable('PATH', 'User') e cerca .local\bin nel PATH che stampa. Se manca, esegui di nuovo i due comandi.

[tab] Windows CMD

Controlla che il programma di installazione abbia messo il programma al suo posto:

dir "%USERPROFILE%\.local\bin\claude.exe"

• File Not Found o The system cannot find the path specified.: non c'è un'installazione nativa. Se non hai installato Claude Code in un altro modo, ad esempio con npm o WinGet, installa Claude Code. Se lo hai installato in un altro modo, vedi Controlla le installazioni in conflitto.
• Un elenco per claude.exe: il programma è presente. Controlla poi il tuo PATH.

Elenca le tue voci PATH e filtra per la cartella di installazione:

echo %PATH% | findstr /i "local\bin"

Se non c'è output, apri Impostazioni di sistema, vai a Variabili di ambiente, e aggiungi %USERPROFILE%\.local\bin alla tua variabile User PATH. Riavvia il tuo terminale.

Verifica che la correzione abbia funzionato:

claude --version

Se claude non viene ancora trovato in un nuovo terminale, tieni presente che un terminale all'interno di un editor prende il suo PATH dall'editor, quindi chiudi e riapri anche l'editor.

Controlla le installazioni in conflitto

Più installazioni di Claude Code possono causare mancate corrispondenze di versione o comportamenti inaspettati. Controlla cosa è installato:

[tab] macOS/Linux

Elenca tutti i binari claude trovati nel tuo PATH:

which -a claude

Se questo stampa claude not found, una riga no claude in, o nulla, nessun claude è nel tuo PATH. I controlli successivi mostrano se ne è installato almeno uno.

Controlla le tre posizioni da cui un binario claude può provenire. ~/.local/bin/claude è il programma di installazione nativo, ~/.claude/local/ è un'installazione npm locale legacy creata da versioni precedenti di Claude Code, e l'elenco npm globale mostra un'installazione -g:

ls -la ~/.local/bin/claude

Un'installazione nativa mostra un collegamento simbolico in ~/.local/share/claude/versions/. Uno script o un collegamento simbolico che hai creato tu stesso in questo percorso è un launcher personalizzato, che l'aggiornamento automatico lascia in posizione.

Se uno dei comandi ls stampa No such file or directory, non è un errore. Significa che nulla è installato in quella posizione, quindi passa al controllo successivo.

ls -la ~/.claude/local/

npm -g ls @anthropic-ai/claude-code 2>/dev/null

Se ls -la ~/.local/bin/claude ha stampato No such file or directory, non c'è un'installazione nativa. Se non hai installato Claude Code in un altro modo, ad esempio con npm, Homebrew o un gestore di pacchetti Linux, installa Claude Code. Se ~/.local/bin/claude esiste ma which -a claude non lo ha elencato, la cartella non è nel tuo PATH: vedi Verifica il tuo PATH.

[tab] Windows PowerShell

Elenca tutti i binari claude trovati nel tuo PATH:

where.exe claude

Se questo stampa INFO: Could not find files for the given pattern(s)., nessun claude è nel tuo PATH.

Controlla se il programma di installazione nativo ha posizionato un binario:

Test-Path "$env:USERPROFILE\.local\bin\claude.exe"

• True: l'installazione nativa è presente. Se where.exe non ha trovato nulla, la sua cartella non è nel tuo PATH: vedi Verifica il tuo PATH.
• False: non c'è un'installazione nativa. Se non hai installato Claude Code in un altro modo, ad esempio con npm o WinGet, installa Claude Code.

Se trovi più installazioni, mantieni solo una. L'installazione nativa in ~/.local/bin/claude su macOS/Linux o %USERPROFILE%\.local\bin\claude.exe su Windows è consigliata. Rimuovi le altre:

Disinstalla un'installazione npm globale:

npm uninstall -g @anthropic-ai/claude-code

Rimuovi l'installazione npm locale legacy:

[tab] macOS/Linux

rm -rf ~/.claude/local

[tab] Windows PowerShell

Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\local"

Rimuovi un'installazione Homebrew su macOS. Se hai installato il cask claude-code@latest, sostituisci quel nome:

brew uninstall --cask claude-code

Rimuovi un'installazione WinGet su Windows:

winget uninstall Anthropic.ClaudeCode

Controlla i permessi della directory

Un'installazione che non riesce a causa dei permessi indica il percorso che non è riuscita a creare o in cui non è riuscita a scrivere. Su Windows l'installazione scrive sotto %USERPROFILE%, che è scrivibile dal tuo utente per impostazione predefinita, quindi questa sezione raramente si applica lì.

Su macOS e Linux l'installazione scrive in queste posizioni:

• ~/.claude/downloads/: dove il comando di installazione mette il binario scaricato
• ~/.local/bin/: il launcher claude
• ~/.local/share/claude/: ogni versione che scarica
• ~/.local/state/claude/: i suoi file di lock
• ~/.cache/claude/: i download in staging
• ~/.claude.json: il tuo file di configurazione globale, dove il programma di installazione registra il metodo di installazione

Se imposti XDG_DATA_HOME, XDG_STATE_HOME o XDG_CACHE_HOME, l'installazione usa questi al posto di ~/.local/share, ~/.local/state e ~/.cache. Se imposti CLAUDE_CONFIG_DIR, il file di configurazione globale si trova in quella directory invece che nella tua directory home.

Controlla se le directory sono scrivibili:

test -w ~/.local/bin && echo "writable" || echo "not writable"
test -w ~/.claude && echo "writable" || echo "not writable"

Se una directory non è scrivibile, crea la directory di installazione e imposta il tuo utente come proprietario:

sudo mkdir -p ~/.local/bin
sudo chown -R $(whoami) ~/.local

Verifica che il binario funzioni

Se claude --version stampa una versione ma claude si arresta in modo anomalo o si blocca all'avvio, esegui questi controlli per restringere la causa. Se claude --version dice comando non trovato, vai a Verifica il tuo PATH prima; i comandi di seguito presuppongono che claude sia nel tuo PATH.

Conferma che il binario esiste ed è eseguibile:

[tab] macOS/Linux

ls -la "$(command -v claude)"

[tab] Windows PowerShell

Get-Command claude | Select-Object Source

Su Linux, controlla le librerie condivise mancanti. Se ldd mostra librerie mancanti, potrebbe essere necessario installare pacchetti di sistema. Su Alpine Linux e altre distribuzioni basate su musl, vedi Configurazione di Alpine Linux.

ldd "$(command -v claude)" | grep "not found"

Conferma che il binario può essere eseguito:

claude --version

Problemi comuni di installazione

Questi sono i problemi di installazione più frequentemente riscontrati e le loro soluzioni.

Lo script di installazione restituisce HTML invece di uno script shell

Il comando di installazione fallisce con uno di questi errori quando ciò che ha scaricato non è lo script di installazione.

Bash o Zsh: l'errore riporta la prima riga della pagina restituita.

bash: line 1: syntax error near unexpected token `<'
bash: line 1: `<!DOCTYPE html>'

PowerShell, errori di analisi: gli errori puntano alla pagina restituita, con iex che tenta di eseguire HTML e CSS come PowerShell.

iex : At line:1 char:2310
+ ... igin="anonymous"/><script type="text/javascript">!function(o,c){var n ...
Missing argument in parameter list.
...

La formulazione varia a seconda della versione di PowerShell e della lingua del sistema: potresti vedere invece Missing expression after unary operator '--' o un ParserError con ParseException. I tag HTML o CSS nel testo riportato identificano questo errore. Se invece scarichi con -OutFile install.ps1, il file salvato è la stessa pagina web, quindi nemmeno questo aiuta.

PowerShell, System.Xml.XmlDocument: l'errore nomina questo tipo invece di riportare la pagina.

System.Xml.XmlDocument : The term 'System.Xml.XmlDocument' is not recognized as the name of a cmdlet, function, script
file, or operable program.

Quando irm riesce ad analizzare la risposta come XML, restituisce un oggetto XML invece di testo, e iex tenta poi di eseguire il nome del tipo di quell'oggetto come comando. Lo script di installazione è codice PowerShell e non viene analizzato come XML, quindi anche questo errore significa che la risposta era qualcosa di diverso dallo script. La formulazione attorno al nome del tipo varia a seconda della versione di PowerShell e della lingua del sistema, ma System.Xml.XmlDocument rimane invariato, quindi basati sul nome del tipo.

CMD: vedi questo errore, seguito dall'HTML della pagina restituita.

< was unexpected at this time.

C:\Users\you><!DOCTYPE html>...

La prima riga appare nella lingua del tuo sistema, quindi cerca l'HTML che la segue.

Un 403 senza pagina: a seconda di come è stata instradata la richiesta, curl segnala uno stato 403 senza corpo HTML.

curl: (22) The requested URL returned error: 403

Tutti questi significano che l'URL di installazione ha restituito una pagina web, un documento XML o uno stato di errore invece dello script di installazione. Se l'output dell'errore riporta "App unavailable in region", Claude Code non è disponibile nel tuo paese. Consulta i paesi supportati.

Un 403 nudo senza corpo spesso ha la stessa causa, ma può anche provenire da un proxy aziendale o da un firewall che blocca il download. Se sei in un paese supportato e vedi ancora il 403, segui Verificare la connettività di rete prima di provare i programmi di installazione alternativi di seguito, poiché raggiungono gli stessi host.

Altrimenti, questo può accadere a causa di problemi di rete, routing regionale o un'interruzione temporanea del servizio.

Soluzioni:

1. Riprova dopo alcuni minuti: il problema è spesso temporaneo. Attendi e riprova il comando originale.

2. Usa un metodo di installazione alternativo: a differenza di un'installazione nativa, un'installazione tramite Homebrew o WinGet non si aggiorna da sola per impostazione predefinita.

   Su macOS, installa tramite Homebrew:

   brew install --cask claude-code
   

   Su Windows, installa tramite WinGet:

   winget install Anthropic.ClaudeCode
   

   Quindi esegui claude --version per confermare: il comando stampa un numero di versione come 2.1.211 (Claude Code). Se la shell segnala che claude non è stato trovato, apri una nuova finestra del terminale e riprova: la sessione da cui hai installato mantiene il vecchio PATH.

command not found: claude dopo l'installazione

L'installazione è terminata ma claude non funziona. L'errore esatto varia a seconda della piattaforma:

Su Windows, se l'errore è comparso subito dopo un aggiornamento di Claude Code, consulta ripristinare claude.exe dal backup.

Altrimenti, consulta Verificare il tuo PATH per la correzione su ogni piattaforma.

permission denied quando aggiungi al PATH

Se il comando echo che aggiunge ~/.local/bin al tuo PATH stampa zsh: permission denied: /Users/you/.zshrc o bash: /home/you/.bashrc: Permission denied, il tuo utente non può scrivere in quel file e non è stato salvato nulla. Nel terminale, verifica chi è il proprietario del file, usando il nome del file della tua shell al posto di ~/.zshrc:

ls -l ~/.zshrc

Il terzo campo dell'output è il proprietario.

• Il proprietario è un altro utente, come root: acquisisci la proprietà con sudo chown $(whoami) ~/.zshrc, che richiede diritti di amministratore.
• Il proprietario sei tu: il file è di sola lettura. Rendilo scrivibile con chmod u+w ~/.zshrc.

Quindi esegui di nuovo i due comandi PATH per la tua shell in Verificare il tuo PATH.

curl: (56) Failure writing output to destination

Il comando curl ... | bash scarica lo script e lo invia a Bash per l'esecuzione. Questo errore, e il correlato curl: (23) Failure writing output to destination, significa che Bash non ha ricevuto lo script completo. Il codice di uscita 56 indica che il download stesso è stato interrotto, e il codice di uscita 23 indica che curl non poteva scrivere ciò che ha ricevuto nella pipe, solitamente perché Bash è uscito prematuramente.

Verifica di poter raggiungere downloads.claude.ai con il controllo in Verificare la connettività di rete. Se hai raggiunto il server, il fallimento originale era probabilmente intermittente; riprova il comando di installazione. Puoi anche provare un metodo di installazione alternativo.

Cask Homebrew non disponibile o obsoleto

Homebrew segnala Error: Cask 'claude-code' is unavailable: No Cask with this name exists quando la copia locale dell'indice cask di Homebrew è precedente alla pubblicazione del cask. Aggiorna l'indice e riprova:

brew update
brew install --cask claude-code

Se Homebrew installa una versione di Claude Code più vecchia di quella prevista, la causa è solitamente lo stesso indice obsoleto. Il cask claude-code segue il canale stabile ed è tipicamente circa una settimana indietro rispetto all'ultima versione; per la versione più recente esegui invece brew install --cask claude-code@latest. Consulta Configurare il canale di rilascio per la differenza tra i due cask.

Cask 'claude-code@latest' is not installed

Homebrew offre due cask, claude-code e claude-code@latest. Eseguire brew upgrade --cask claude-code@latest quando il cask installato non è quello stampa Error: Cask 'claude-code@latest' is not installed. Per vedere quale cask hai, esegui questo nel terminale:

brew list --cask | grep claude-code

Aggiorna il cask che viene stampato. Se non stampa nulla, nessuno dei due cask è installato.

Errori di connessione TLS o SSL

Errori come questi significano che l'handshake TLS è fallito:

• curl: (35) TLS connect error
• schannel: next InitializeSecurityContext failed
• Could not create SSL/TLS secure channel di PowerShell
• Could not establish trust relationship for the SSL/TLS secure channel di PowerShell

Per CRYPT_E_NO_REVOCATION_CHECK o CRYPT_E_REVOCATION_OFFLINE, vai al passaggio 4.

Soluzioni:

1. Aggiorna i certificati CA del sistema:

   Su Ubuntu/Debian:

   sudo apt-get update && sudo apt-get install ca-certificates
   

   Su macOS, il curl di sistema utilizza l'archivio di fiducia Keychain; l'aggiornamento di macOS stesso aggiorna i certificati root.

2. In Windows PowerShell 5.1, abilita TLS 1.2:

   [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
   

   Quindi esegui il programma di installazione nella stessa finestra:

   irm https://claude.ai/install.ps1 | iex
   

3. Verifica l'interferenza di proxy o firewall: i proxy aziendali che eseguono l'ispezione TLS possono causare questi errori, inclusi unable to get local issuer certificate, unable to verify the first certificate e SELF_SIGNED_CERT_IN_CHAIN. Fai in modo che il download di installazione si fidi della CA del proxy aziendale:

   [tab] macOS/Linux

   Imposta CURL_CA_BUNDLE per i download curl dello script di installazione, e NODE_EXTRA_CA_CERTS per il comando claude install che lo script esegue successivamente. Se non ce l'hai, chiedi al tuo team IT un file PEM con il certificato CA root del proxy. Questo esempio imposta entrambe le variabili sul file CA del proxy ed esegue lo script nello stesso terminale:

   export CURL_CA_BUNDLE=/path/to/corporate-ca.pem
   export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
   curl -fsSL https://claude.ai/install.sh | bash
   

   Se l'installazione fallisce ancora con uno di quegli errori di certificato, chiedi al tuo team IT un file che contenga sia i certificati root pubblici sia l'intera catena CA del proxy. Quindi imposta entrambe le variabili su quel file.

   [tab] Windows PowerShell

   Il programma di installazione PowerShell scarica tramite .NET, che convalida TLS rispetto all'archivio certificati di Windows. Chiedi al tuo team IT di aggiungere il certificato CA del proxy all'archivio di Windows se non è già presente, quindi esegui il programma di installazione:

   irm https://claude.ai/install.ps1 | iex
   

   Per Claude Code stesso una volta installato, imposta NODE_EXTRA_CA_CERTS in modo che le richieste API si fidino dello stesso bundle:

   [tab] macOS/Linux

   export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
   

   [tab] Windows PowerShell

   $env:NODE_EXTRA_CA_CERTS = 'C:\path\to\corporate-ca.pem'
   

4. Su Windows, aggira i controlli di revoca bloccati. Gli errori CRYPT_E_NO_REVOCATION_CHECK (0x80092012) e CRYPT_E_REVOCATION_OFFLINE (0x80092013) significano che curl ha raggiunto il server ma la tua rete blocca la verifica di revoca del certificato, cosa comune dietro i firewall aziendali. Se il comando che fallisce è il curl che scarica install.cmd, rieseguilo da un Command Prompt aggiungendo --ssl-revoke-best-effort:

   curl --ssl-revoke-best-effort -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
   

   Quando i download dello script stesso incontrano gli stessi errori, lo script li riprova automaticamente con il controllo di revoca best-effort, quindi il flag è necessario solo sul comando che esegui tu. Il controllo best-effort tollera un server di revoca irraggiungibile ma rifiuta comunque un certificato noto come revocato, allo stesso modo in cui i browser gestiscono la revoca. Puoi anche evitare completamente il controllo di revoca di curl eseguendo il programma di installazione PowerShell da PowerShell, che scarica tramite .NET e non fallisce quando il server di revoca è irraggiungibile:

   irm https://claude.ai/install.ps1 | iex
   

   Puoi anche installare con winget install Anthropic.ClaudeCode, che evita completamente curl.

Failed to fetch version from downloads.claude.ai

La parte finale del messaggio indica il motivo. Se si tratta di un errore di certificato come unable to verify the first certificate, consulta Errori di connessione TLS o SSL. Per qualsiasi altro motivo, consulta Verificare la connettività di rete.

The connection dropped while downloading the update

La connessione al server di download si è chiusa mentre claude install o claude update scaricava il binario di Claude Code, e i nuovi tentativi non hanno risolto. Claude Code riprova il download quando la connessione cade, il trasferimento si blocca o il file scaricato non supera la verifica del checksum, fino a tre tentativi in totale. Un errore HTTP completato, come un 404, non viene riprovato perché il server ha già risposto. Prima della v2.1.202, una singola connessione interrotta faceva fallire immediatamente il download con il semplice errore aborted invece di riprovare.

The connection dropped while downloading the update (attempt 3/3: aborted). Check your network — proxies sometimes cut off large downloads.

Il testo tra parentesi indica quale tentativo è fallito e l'errore di rete sottostante. claude update fa precedere il messaggio da Error: Failed to install native update su stderr.

Un download che resta connesso ma non termina entro 10 minuti fallisce invece con Download timed out: exceeded the total deadline. Claude Code non riprova un download scaduto, perché una connessione troppo lenta per terminare entro la scadenza non terminerà nemmeno con un nuovo tentativo immediato. I passaggi seguenti valgono per entrambi i messaggi.

Un proxy o un gateway può chiudere un trasferimento lungo prima che termini, e il binario di Claude Code è un download di grandi dimensioni.

Cosa fare:

• Esegui di nuovo claude update. Su una rete altrimenti funzionante, il download di solito riesce all'esecuzione successiva. Per il messaggio di timeout, eseguilo di nuovo da una rete più veloce o meno limitata.
• Se la tua rete richiede un proxy, imposta HTTPS_PROXY prima di eseguire il programma di installazione o claude update. Consulta Verificare la connettività di rete.
• Se un proxy aziendale continua a chiudere il trasferimento, chiedi al tuo team di rete di consentire il download completo da downloads.claude.ai. Consulta Requisiti di accesso alla rete.
• Esegui claude doctor dalla tua shell per la diagnostica dell'installazione

Release verification failed for Claude Code

Questo messaggio di claude update o claude install significa che Claude Code non è riuscito a confermare che la versione che stava per installare sia autentica, quindi non ha installato nulla. Qualsiasi versione già presente continua a funzionare.

Release verification failed for Claude Code <version> (<reason>). The update was not installed.

Esegui il passaggio corrispondente al valore tra parentesi nel tuo messaggio:

• Un valore che inizia con sidecar_fetch_: esegui di nuovo lo stesso comando dalla tua shell. claude update è riuscito se stampa una riga che inizia con Successfully updated from, e claude install è riuscito se stampa Claude Code successfully installed!.
• Qualsiasi altro valore: riprova lo stesso comando più tardi

Con qualsiasi valore, se il messaggio si ripete, segnala il problema includendo il messaggio completo.

Auto-update failed · Run claude doctor nel piè di pagina della sessione

Questa riga rossa significa che Claude Code ha tentato di aggiornarsi in background e l'aggiornamento non è stato installato. Puoi continuare a lavorare senza fare nulla.

La riga ti indirizza a claude doctor, la cui riga Last update attempt: failed (install_failed) fornisce una data ma non una causa. Per completare l'aggiornamento o scoprire perché è fallito, esegui invece claude update nella tua shell. Se anche quell'installazione fallisce, cerca l'errore stampato da claude update in Trovare il tuo errore.

Comando di installazione errato su Windows

Se vedi 'irm' is not recognized, The token '&&' is not a valid statement separator, A parameter cannot be found that matches parameter name 'fsSL' o 'bash' is not recognized as the name of a cmdlet, hai copiato il comando di installazione per una shell o un sistema operativo diverso. Se il comando stampa il testo dello script invece di installare qualcosa, ne hai eseguito solo una parte.

• irm non riconosciuto: sei in CMD, non in PowerShell. Hai due opzioni:

  Apri PowerShell cercando "PowerShell" nel menu Start, quindi esegui il comando di installazione originale:

  irm https://claude.ai/install.ps1 | iex
  

  Oppure rimani in CMD e usa invece il programma di installazione CMD:

  curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
  

• && non è un separatore di istruzioni valido: sei in PowerShell ma hai eseguito il comando del programma di installazione CMD. Usa il programma di installazione PowerShell:

  irm https://claude.ai/install.ps1 | iex
  

• A parameter cannot be found that matches parameter name 'fsSL': hai eseguito il programma di installazione curl -fsSL ... | bash di macOS/Linux in Windows PowerShell, dove curl è un alias per Invoke-WebRequest e rifiuta i flag -fsSL. Usa invece il programma di installazione PowerShell:

  irm https://claude.ai/install.ps1 | iex
  

• bash non riconosciuto: hai eseguito il programma di installazione di macOS/Linux su Windows. Usa invece il programma di installazione PowerShell:

  irm https://claude.ai/install.ps1 | iex
  

• Il comando stampa il testo dello script invece di installare: hai eseguito la metà del comando che scarica senza la parte che lo esegue. irm https://claude.ai/install.ps1 da solo stampa lo script scaricato nel terminale. Invialo a iex per eseguirlo:

  irm https://claude.ai/install.ps1 | iex
  

  In CMD, curl -fsSL https://claude.ai/install.cmd senza -o stampa lo script batch invece di salvarlo. Esegui il comando completo:

  curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
  

Qualunque programma di installazione usi, verifica che abbia funzionato: apri un nuovo terminale ed esegui claude --version, che stampa un numero di versione come 2.1.211 (Claude Code).

running scripts is disabled on this system

L'installazione o l'esecuzione di Claude Code tramite npm su Windows può fallire con un SecurityError:

npm : File C:\Program Files\nodejs\npm.ps1 cannot be loaded because running scripts is disabled on this system. For more information, see about_Execution_Policies at https:/go.microsoft.com/fwlink/?LinkID=135170.
...
    + CategoryInfo          : SecurityError: (:) [], PSSecurityException

Lo stesso errore nomina claude.ps1 quando esegui claude dopo un'installazione npm. La politica di esecuzione di PowerShell sta bloccando gli script launcher .ps1 che npm crea per i suoi comandi. La politica si applica ai file di script, quindi non influisce sul programma di installazione PowerShell irm https://claude.ai/install.ps1 | iex, che esegue direttamente il testo scaricato.

Soluzioni:

1. Consenti gli script creati localmente per il tuo utente, quindi riprova:

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
   

2. Chiama invece il launcher .cmd: npm.cmd e claude.cmd fanno lo stesso lavoro, e la politica non li copre.
3. Usa il programma di installazione PowerShell invece di npm. Installa un binario anziché uno script .ps1.

The process cannot access the file durante l'installazione su Windows

Se il programma di installazione PowerShell fallisce con Failed to download binary: The process cannot access the file ... because it is being used by another process, il programma di installazione non è riuscito a scrivere in %USERPROFILE%\.claude\downloads. Questo solitamente significa che un tentativo di installazione precedente è ancora in esecuzione, o che il software antivirus sta scansionando un binario parzialmente scaricato in quella cartella.

Chiudi qualsiasi altra finestra PowerShell che esegue il programma di installazione e attendi che le scansioni antivirus rilascino il file. Quindi elimina la cartella dei download ed esegui di nuovo il programma di installazione:

Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\downloads"
irm https://claude.ai/install.ps1 | iex

claude.exe mancante dopo un aggiornamento su Windows

Se il tuo terminale segnala 'claude' is not recognized subito dopo un aggiornamento di Claude Code su Windows, verifica se %USERPROFILE%\.local\bin contiene ancora claude.exe. Se quella directory non è affatto nel tuo PATH, consulta invece Verificare il tuo PATH. Per aggiornarsi su Windows, Claude Code rinomina il claude.exe esistente come backup e sposta la nuova versione al suo posto. Se lo spostamento della nuova versione fallisce e Claude Code non riesce nemmeno a ripristinare il nome del backup, la directory conserva il backup ma non contiene claude.exe.

Il backup è un file nella stessa directory il cui nome inizia con claude.exe.old. seguito da un timestamp numerico. Esegui quanto segue in PowerShell per rinominare il backup più recente in claude.exe:

Get-ChildItem "$env:USERPROFILE\.local\bin\claude.exe.old.*" | Sort-Object Name | Select-Object -Last 1 | Rename-Item -NewName claude.exe

Quindi esegui claude --version per confermare la correzione. Un claude.exe ripristinato stampa un numero di versione.

Se non c'è un file claude.exe.old.*, o claude fallisce ancora dopo la ridenominazione, reinstalla:

irm https://claude.ai/install.ps1 | iex

Prima della v2.1.281, Claude Code poteva eliminare il backup mentre claude.exe era ancora mancante.

Installazione interrotta su server Linux con poca memoria

Un messaggio Killed durante l'installazione solitamente significa che l'OOM killer (out-of-memory) di Linux ha terminato il passaggio claude install perché il sistema ha esaurito la memoria libera. Questo è comune su piccoli VPS e istanze cloud. Lo script di installazione segnala la causa ed esce con il codice 137. In questo esempio, il numero di riga e l'ID del processo variano a seconda della versione e dell'esecuzione:

Setting up Claude Code...
bash: line 183: 34803 Killed    "$binary_path" install ${TARGET:+"$TARGET"}
Installation was killed before it could finish (exit code 137). This usually means the system ran out of memory.
Claude Code needs roughly 512MB of free memory to install. Free up memory, then run this script again.

L'installazione richiede circa 512 MB di memoria libera, e l'esecuzione di Claude Code ne richiede di più. Consulta i requisiti di sistema.

Soluzioni:

1. Aggiungi spazio di swap se il tuo server ha RAM limitata. Lo swap utilizza lo spazio su disco come memoria aggiuntiva, permettendo all'installazione di completarsi anche con poca RAM fisica.

   Crea un file di swap di 2 GB e abilitalo:

   sudo fallocate -l 2G /swapfile
   sudo chmod 600 /swapfile
   sudo mkswap /swapfile
   sudo swapon /swapfile
   

   Quindi riprova l'installazione:

   curl -fsSL https://claude.ai/install.sh | bash
   

2. Chiudi altri processi per liberare memoria prima di installare.

3. Usa un'istanza più grande se possibile. Claude Code richiede almeno 4 GB di RAM.

Installation was killed before it could finish

Lo script di installazione segnala quando il passaggio claude install viene terminato da un segnale. Su Linux, il codice di uscita 137 significa che il processo ha ricevuto SIGKILL, e su un host con poca memoria questo è solitamente l'OOM killer (out-of-memory) del kernel. Lo script stampa questa spiegazione ed esce con il codice 137:

Installation was killed before it could finish (exit code 137). This usually means the system ran out of memory.
Claude Code needs roughly 512MB of free memory to install. Free up memory, then run this script again.

Per qualsiasi altro segnale fatale, e per il codice di uscita 137 su macOS, lo script stampa Installation was killed before it could finish (exit code <N>) con il codice di uscita effettivo e omette la spiegazione sulla memoria esaurita. Il messaggio proviene dallo script di installazione usato da macOS e Linux, che copre anche le installazioni all'interno di WSL; gli script di installazione nativi per Windows non lo stampano mai. Prima della v2.1.200, lo script usciva solo con la semplice riga Killed della shell.

Cosa fare:

• Arresta altri processi per liberare memoria, quindi riesegui il programma di installazione
• Aggiungi spazio di swap o passa a un'istanza più grande. Consulta Installazione interrotta su server Linux con poca memoria per i comandi del file di swap.

L'installazione si blocca in Docker

Quando installi Claude Code in un contenitore Docker, l'installazione come root in / può causare blocchi.

Soluzioni:

1. Imposta una directory di lavoro prima di eseguire il programma di installazione. Quando viene eseguito da /, il programma di installazione scansiona l'intero filesystem, il che causa un utilizzo eccessivo della memoria. Impostare WORKDIR limita la scansione a una piccola directory:

   WORKDIR /tmp
   RUN curl -fsSL https://claude.ai/install.sh | bash
   

2. Assegna più memoria a Docker se usi Docker Desktop. I contenitori di build condividono la memoria allocata alla macchina virtuale di Docker Desktop, quindi apri Settings > Resources in Docker Desktop, aumenta il limite di memoria e riesegui la build.

Raw mode is not supported durante l'installazione

Quando le impostazioni gestite dal server della tua organizzazione includono modifiche che richiedono l'approvazione di sicurezza, le versioni di Claude Code precedenti alla 2.1.246 tentano di mostrare la finestra di dialogo di approvazione durante claude install. La finestra di dialogo richiede un terminale su stdin. Quando il programma di installazione esegue claude install da una pipe, come fa curl -fsSL https://claude.ai/install.sh | bash, stdin è la pipe anziché un terminale, quindi l'installazione fallisce con un errore contenente Raw mode is not supported.

Claude Code v2.1.246 e successive non mostrano la finestra di dialogo durante claude install o claude update. Il comando viene eseguito con le impostazioni che hai approvato l'ultima volta, e Claude Code mostra la finestra di dialogo nella tua prossima sessione interattiva. Se la configurazione di avvio della tua organizzazione attende il recupero delle impostazioni, ad esempio quando imposta forceRemoteSettingsRefresh, la finestra di dialogo appare comunque durante questi comandi, e un'installazione eseguita da una pipe fallisce comunque.

In ogni altra configurazione, rieseguire il programma di installazione supera questo errore, perché lo script esegue il comando install della versione più recente anche quando chiedi di installare una versione precedente. Riesegui il comando per la tua piattaforma:

[tab] macOS/Linux

curl -fsSL https://claude.ai/install.sh | bash

[tab] Windows PowerShell

irm https://claude.ai/install.ps1 | iex

claude --version stampa la versione installata dalla riesecuzione.

claude update o claude doctor si blocca

claude update e claude doctor scansionano i file di configurazione della shell alla ricerca di un alias claude obsoleto: ~/.zshrc, ~/.bashrc e ~/.config/fish/config.fish, più, su macOS, il primo esistente tra ~/.bash_profile, ~/.bash_login o ~/.profile. Se imposti ZDOTDIR, il file Zsh è invece $ZDOTDIR/.zshrc. Quando uno di questi percorsi è una directory, Claude Code lo salta ed entrambi i comandi si completano normalmente. Prima della v2.1.214, una directory in uno di questi percorsi faceva bloccare entrambi i comandi e lasciava vuota la sezione System diagnostics di /status. claude doctor si bloccava senza output; claude update si bloccava subito dopo aver stampato Checking for updates.

Se incontri il blocco su una versione precedente, trova la directory. Nell'output di questo comando, una riga che inizia con d indica che quel percorso è una directory. Una riga No such file or directory significa che in quel percorso non esiste nulla e non è la causa:

ls -ld ~/.zshrc ~/.bashrc ~/.bash_profile ~/.bash_login ~/.profile ~/.config/fish/config.fish

Sposta la directory altrove, oppure aggiorna alla v2.1.214 o successiva. Poiché claude update si blocca sulle versioni interessate, aggiorna invece rieseguendo lo script di installazione.

Claude Desktop sovrascrive il comando claude su Windows

Se hai installato una versione precedente di Claude Desktop, potrebbe registrare un Claude.exe nella directory WindowsApps che ha la precedenza nel PATH su Claude Code CLI. L'esecuzione di claude apre l'app Desktop invece della CLI.

Aggiorna Claude Desktop all'ultima versione per risolvere questo problema.

Claude Code su Windows richiede Git for Windows (per bash) o PowerShell

Git for Windows è opzionale. Claude Code utilizza lo strumento PowerShell quando Git Bash è assente, quindi questo errore significa che non è stata trovata nessuna delle due shell.

Se PowerShell manca dal tuo PATH, la sua posizione predefinita è C:\Windows\System32\WindowsPowerShell\v1.0\. Aggiungi quella directory al tuo PATH, oppure installa PowerShell 7, che fornisce pwsh.

Per installare invece Git for Windows, scaricalo da git-scm.com/downloads/win. Durante l'installazione, seleziona "Add to PATH". Riavvia il terminale dopo l'installazione. Installarlo abilita lo strumento Bash, utile quando lavori con script e strumenti basati su Bash.

Se Git è già installato ma Claude Code non riesce a trovarlo, confronta la sua posizione con i percorsi in cui Claude Code cerca. Quando CLAUDE_CODE_GIT_BASH_PATH non è impostato, Claude Code cerca bash.exe in questo ordine:

1. Le posizioni di installazione predefinite C:\Program Files\Git e C:\Program Files (x86)\Git.
2. Il git nel tuo PATH, utilizzando il bin\bash.exe di quella installazione di Git.

Nel passaggio 2, Claude Code salta un git che si trova nella cartella da cui hai avviato Claude Code, o sotto di essa in un percorso che contiene node_modules o una cartella di ambiente virtuale come .venv o env, ad esempio C:\dev\env\myproject\Git quando hai avviato da C:\dev\env\myproject. Questo impedisce a Claude Code di eseguire un eseguibile che un progetto ha messo lì. Se il tuo Git si trova in una posizione di questo tipo, fai puntare CLAUDE_CODE_GIT_BASH_PATH ad esso.

Per far puntare Claude Code a un'installazione Git specifica, trovala eseguendo where.exe git in PowerShell, quindi imposta il percorso bin\bash.exe di quella installazione come CLAUDE_CODE_GIT_BASH_PATH nel tuo file settings.json:

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

Se CLAUDE_CODE_GIT_BASH_PATH è impostato sul percorso corretto e il file esiste ma Claude Code ancora non lo utilizza, controlla prima il nome del file. Claude Code accetta solo un file denominato bash.exe, sh.exe, bash o sh; con qualsiasi altro nome, come il launcher git-bash.exe di Git for Windows, ignora la variabile e rileva automaticamente Git Bash come se non fosse impostata, registrando un avviso visibile con --debug. Un percorso che non esiste ottiene lo stesso fallback e lo stesso avviso. Prima della v2.1.219, Claude Code utilizzava qualsiasi file esistente come shell senza controllarne il nome, e usciva all'avvio con Claude Code was unable to find CLAUDE_CODE_GIT_BASH_PATH path quando il percorso non esisteva.

Se il nome del file è corretto, potrebbe interferire un software di sicurezza degli endpoint come AppLocker, le politiche di restrizione software di Group Policy o gli agenti EDR. Chiedi al tuo team IT di aggiungere all'allowlist claude.exe e i processi che genera, inclusi cmd.exe e bash.exe, nella tua politica di protezione degli endpoint.

Claude Code non supporta Windows a 32 bit

Windows include due voci di PowerShell nel menu Start: Windows PowerShell e Windows PowerShell (x86). La voce x86 viene eseguita come processo a 32 bit e genera questo errore anche su una macchina a 64 bit. Per verificare in quale caso ti trovi, esegui questo nella stessa finestra che ha prodotto l'errore:

[Environment]::Is64BitOperatingSystem

Se stampa True, il tuo sistema operativo va bene. Chiudi la finestra, apri Windows PowerShell senza il suffisso x86 ed esegui di nuovo il comando di installazione.

Se stampa False, stai usando un'edizione di Windows a 32 bit. Claude Code richiede un sistema operativo a 64 bit. Consulta i requisiti di sistema.

Mancata corrispondenza del binario musl o glibc su Linux

Se vedi errori relativi a librerie condivise mancanti come libstdc++.so.6 o libgcc_s.so.1 dopo l'installazione, il programma di installazione potrebbe aver scaricato la variante di binario sbagliata per il tuo sistema.

Error loading shared library libstdc++.so.6: No such file or directory

Questo può accadere su sistemi basati su glibc che hanno installati pacchetti di cross-compilazione musl, inducendo il programma di installazione a rilevare erroneamente il sistema come musl.

Soluzioni:

1. Verifica quale libc utilizza il tuo sistema:

   ldd --version 2>&1 | head -1
   

   Un output che menziona GNU libc o GLIBC significa glibc. Un output che menziona musl significa musl.

2. Se sei su glibc ma hai ottenuto il binario musl, rimuovi l'installazione e reinstalla. Puoi anche scaricare manualmente il binario corretto utilizzando il manifest in https://downloads.claude.ai/claude-code-releases/{VERSION}/manifest.json. Apri una issue su GitHub con l'output di ldd --version e ls /lib/libc.musl*.

3. Se sei effettivamente su musl, come Alpine Linux, installa i pacchetti richiesti:

   apk add libgcc libstdc++ ripgrep
   

   Su Alpine, ripgrep si trova nel repository community. Se apk segnala che il pacchetto manca, consulta Configurazione di Alpine Linux.

Illegal instruction

Se l'esecuzione di claude o del programma di installazione stampa Illegal instruction, il binario nativo utilizza istruzioni CPU che il tuo processore non supporta. Ci sono due cause distinte.

Mancata corrispondenza dell'architettura. Il programma di installazione ha scaricato il binario sbagliato, ad esempio x86 su un server ARM. Verifica con uname -m su macOS o Linux, o $env:PROCESSOR_ARCHITECTURE in PowerShell. Se il risultato non corrisponde al binario che hai ricevuto, apri una issue su GitHub con l'output.

Set di istruzioni AVX mancante. Se la tua architettura è corretta ma vedi ancora Illegal instruction, probabilmente la tua CPU non dispone di AVX o di un'altra istruzione richiesta dal binario. Questo riguarda all'incirca i processori Intel e AMD precedenti al 2013, e le macchine virtuali in cui l'hypervisor non passa AVX al guest.

Su un VPS o una VM, esegui grep -m1 -ow avx /proc/cpuinfo; un risultato vuoto significa che AVX non è disponibile per il guest.

Non esiste una soluzione alternativa con il binario nativo; segui la issue #50384 per lo stato e, quando segnali il problema, includi il modello della tua CPU ottenuto da grep -m1 "model name" /proc/cpuinfo su Linux o sysctl -n machdep.cpu.brand_string su macOS.

I metodi di installazione alternativi scaricano lo stesso binario nativo e non risolvono nessuna delle due cause.

dyld: cannot load su macOS

Se vedi dyld: Symbol not found, dyld: cannot load o Abort trap: 6 durante l'installazione, il binario è incompatibile con la tua versione di macOS o con il tuo hardware.

Un errore Symbol not found che fa riferimento a libicucore significa che la tua versione di macOS è più vecchia di quelle supportate dal binario:

dyld: Symbol not found: _ubrk_clone
  Referenced from: claude-darwin-x64 (which was built for Mac OS X 13.0)
  Expected in: /usr/lib/libicucore.A.dylib

Il loader può invece rifiutare i comandi di caricamento del binario, il che significa anche che la tua versione di macOS è troppo vecchia:

dyld: cannot load 'claude-2.1.42-darwin-x64' (load command 0x80000034 is unknown)
Abort trap: 6

Soluzioni:

1. Verifica la tua versione di macOS: Claude Code richiede macOS 13.0 o successivo. Apri il menu Apple e seleziona About This Mac per verificare la tua versione.

2. Aggiorna macOS se usi una versione precedente. Il binario utilizza comandi di caricamento e librerie di sistema che le versioni precedenti di macOS non supportano. I metodi di installazione alternativi come Homebrew scaricano lo stesso binario e non risolvono questo errore.

Bus error durante una sessione in esecuzione

Se una sessione in esecuzione termina e la tua shell stampa Bus error, una possibile causa è che Claude Code non riusciva più a leggere dal disco il proprio file eseguibile. Ad esempio, il file è stato troncato, o eliminato su uno storage di rete, mentre la sessione era in esecuzione.

Prima del messaggio della shell, il runtime di Claude Code può stampare un rapporto di arresto anomalo che include panic(main thread): Bus error at address e oh no: Bun has crashed. This indicates a bug in Bun, not your code. Quando l'eseguibile è diventato illeggibile, l'arresto anomalo deriva dal file illeggibile, non da un bug di Bun. Il rapporto può anche mancare, se il runtime non è riuscito a leggere nemmeno il codice che lo stampa.

Avvia una nuova sessione per continuare. Se Claude Code è installato su uno storage di rete, segui Installare su storage di rete in modo che gli aggiornamenti non rimuovano un binario ancora necessario alle sessioni in esecuzione.

Exec format error su WSL1

Se l'esecuzione di claude in WSL stampa cannot execute binary file: Exec format error, sei su WSL1 e stai incontrando una regressione nota del binario nativo, tracciata nella issue #38788. Le intestazioni di programma del binario sono cambiate in un modo che il loader di WSL1 non riesce a gestire.

La correzione più pulita è convertire la tua distribuzione a WSL2 da PowerShell:

wsl --set-version <DistroName> 2

Se devi rimanere su WSL1, invoca il binario tramite il linker dinamico. Aggiungi questa funzione a ~/.bashrc all'interno di WSL, sostituendo il percorso se la tua directory home è diversa:

claude() {
  /lib64/ld-linux-x86-64.so.2 "$(readlink -f "$HOME/.local/bin/claude")" "$@"
}

Quindi esegui source ~/.bashrc e riprova claude.

Errori di installazione npm in WSL

Questi problemi si applicano se hai installato Claude Code con npm install -g all'interno di WSL. Se hai usato il programma di installazione nativo, salta questa sezione. Su npm 12, installa come descritto in Correggere un'installazione con npm 12.

Problemi di rilevamento del sistema operativo o della piattaforma. Se npm segnala una mancata corrispondenza della piattaforma durante l'installazione, probabilmente WSL sta usando il npm di Windows. Esegui prima npm config set os linux, quindi installa con npm install -g @anthropic-ai/claude-code --force. Non usare sudo.

exec: node: not found quando esegui claude. Probabilmente il tuo ambiente WSL sta usando l'installazione di Node.js di Windows. Verificalo con which npm e which node: i percorsi che iniziano con /mnt/c/ sono binari di Windows, mentre i percorsi Linux iniziano con /usr/. Per risolvere, installa Node tramite il gestore di pacchetti della tua distribuzione Linux o tramite nvm.

Conflitti di versione nvm. Se hai nvm installato sia in WSL che in Windows, il cambio di versione di Node in WSL potrebbe non funzionare perché WSL importa il PATH di Windows per impostazione predefinita e l'nvm di Windows ha la priorità. La causa più comune è che nvm non è caricato nella tua shell. Aggiungi il caricatore di nvm a ~/.bashrc o ~/.zshrc:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

Oppure caricalo nella sessione corrente:

source ~/.nvm/nvm.sh

Se nvm è caricato ma i percorsi di Windows hanno ancora la priorità, anteponi esplicitamente il percorso di Node per Linux:

export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"

[!WARNING]

Evita di disabilitare l'importazione del PATH di Windows tramite appendWindowsPath = false, poiché questo impedisce di chiamare eseguibili di Windows da WSL. Allo stesso modo, evita di disinstallare Node.js da Windows se lo usi per lo sviluppo su Windows.

Errori di permesso durante l'installazione

Se il programma di installazione nativo fallisce con errori di permesso, la directory di destinazione potrebbe non essere scrivibile. Consulta Verificare i permessi della directory.

Se in precedenza hai installato con npm e incontri errori di permesso specifici di npm, passa al programma di installazione nativo:

curl -fsSL https://claude.ai/install.sh | bash

Binario nativo non trovato dopo l'installazione npm

Il pacchetto npm @anthropic-ai/claude-code scarica il binario nativo come dipendenza opzionale specifica per piattaforma, come @anthropic-ai/claude-code-darwin-arm64. claude è uno script segnaposto finché non viene eseguito il passaggio postinstall del pacchetto @anthropic-ai/claude-code, che sostituisce il segnaposto con quel binario. Se il download o il passaggio postinstall viene saltato, il segnaposto rimane al suo posto, e l'esecuzione di claude su macOS e Linux stampa:

Error: claude native binary not installed.

Either postinstall did not run (--ignore-scripts, some pnpm configs)
or the platform-native optional dependency was not downloaded
(--omit=optional).

Run the postinstall manually (adjust path for local vs global install):
  node node_modules/@anthropic-ai/claude-code/install.cjs

Or reinstall without --ignore-scripts / --omit=optional.

Su Windows, bin/claude.exe è lo stesso segnaposto in forma di script shell anziché un vero eseguibile, quindi PowerShell e CMD segnalano di non poter eseguire il file invece di stampare questo messaggio.

Verifica le seguenti cause:

• npm 12 salta il passaggio postinstall per impostazione predefinita. Quando installi o aggiorni Claude Code con npm 12, npm completa comunque l'installazione senza eseguire il passaggio. Consulta Correggere un'installazione con npm 12.
• Le dipendenze opzionali sono disabilitate. Rimuovi --omit=optional dal tuo comando di installazione npm, --no-optional da pnpm o --ignore-optional da yarn, e verifica che .npmrc non imposti optional=false. Quindi reinstalla. Il binario nativo viene fornito solo come dipendenza opzionale, quindi non esiste un fallback JavaScript se viene saltato, ed eseguire di nuovo install.cjs non può posizionare un binario che non è mai stato scaricato.
• Gli script di installazione sono disabilitati. --ignore-scripts e alcune configurazioni di pnpm saltano il passaggio postinstall ma scaricano comunque il pacchetto della piattaforma. Esegui node node_modules/@anthropic-ai/claude-code/install.cjs come suggerisce il messaggio, oppure reinstalla senza il flag. Se postinstall non può essere eseguito affatto nel tuo ambiente, node node_modules/@anthropic-ai/claude-code/cli-wrapper.cjs trova il pacchetto scaricato e lo avvia, al costo di un processo Node aggiuntivo a ogni avvio. Se invece il wrapper stampa Could not find native binary package, il pacchetto della piattaforma non è mai stato scaricato, quindi correggi prima la causa relativa alle dipendenze opzionali descritta sopra.
• Piattaforma non supportata. I binari precompilati sono pubblicati per darwin-arm64, darwin-x64, linux-x64, linux-arm64, linux-x64-musl, linux-arm64-musl, win32-x64 e win32-arm64. Claude Code non distribuisce un binario per altre piattaforme; consulta i requisiti di sistema. Su FreeBSD, il programma di installazione segnala la piattaforma come non supportata. Prima della v2.1.205, trattava FreeBSD come Linux e scaricava un binario che non poteva essere eseguito.
• Il mirror npm aziendale non contiene i pacchetti della piattaforma. Assicurati che il tuo registro esegua il mirroring di tutti gli otto pacchetti di piattaforma @anthropic-ai/claude-code-* oltre al meta-pacchetto.

Correggere un'installazione con npm 12

Se claude stampa Error: claude native binary not installed. dopo un'installazione o un aggiornamento npm, oppure su Windows la shell non riesce a eseguirlo, esegui npm --version. Una versione che inizia con 12 significa che, a meno che la tua configurazione npm non lo consenta, npm ha saltato il passaggio postinstall di Claude Code, che mette il binario al suo posto. Per qualsiasi altra versione, verifica le altre cause.

Per correggere un'installazione con npm 12, passa al programma di installazione nativo oppure consenti il passaggio:

• Passa al programma di installazione nativo: installa con il programma di installazione nativo, quindi disinstalla il pacchetto npm. Gli aggiornamenti non usano più npm, quindi l'errore non si ripresenta.

• Resta su npm: per un'installazione npm globale, aggiungi Claude Code a allow-scripts nella configurazione npm del tuo utente. npm eseguirà quindi gli script di installazione di Claude Code a ogni installazione e aggiornamento successivo, e nelle installazioni di progetto il cui package.json non imposta allowScripts.

  Usa il programma di installazione nativo per un'installazione locale in ~/.claude/local. Usalo anche se gli script del tuo package.json chiamano npm install e li esegui con pnpm 9, pnpm 10, Yarn 1 o un altro strumento che passa loro questa impostazione. Su npm 12.1 e successive, quelle installazioni possono fallire con EALLOWSCRIPTS una volta salvata l'impostazione.

  1. Se npm --version ha stampato 12.0.x, aggiorna npm alla 12.1 o successiva, ad esempio con npm install -g npm@latest. Sulla 12.0.x, le installazioni di progetto avviate da uno strumento npx o da uno script npm run possono fallire con EALLOWSCRIPTS una volta salvata l'impostazione.

  2. Esegui npm config get allow-scripts e annota gli eventuali pacchetti elencati, perché il comando successivo sostituisce l'intero valore. Salva l'impostazione con quei pacchetti all'interno delle virgolette, come in "allow-scripts=@anthropic-ai/claude-code,<package>":

     npm config set "allow-scripts=@anthropic-ai/claude-code" --location=user
     

  3. Reinstalla:

     npm install -g @anthropic-ai/claude-code
     

     Se questo comando o il passaggio 1 fallisce con EACCES, passa al programma di installazione nativo invece di rieseguirlo con sudo. Claude Code esegue npm senza sudo quando si aggiorna, quindi gli aggiornamenti automatici fallirebbero allo stesso modo.

  4. Se claude --version non stampa un numero di versione, verifica le altre cause.

  Per annullare, imposta di nuovo l'elenco senza @anthropic-ai/claude-code, oppure rimuovi l'intero elenco con npm config delete allow-scripts --location=user. Su npm 12, l'errore si ripresenta quindi dopo il tuo prossimo aggiornamento.

Errore npm ENOTEMPTY durante l'aggiornamento o la reinstallazione

Quando esegui npm install -g @anthropic-ai/claude-code su un'installazione esistente, npm può fallire mentre sposta da parte la vecchia directory del pacchetto:

npm error code ENOTEMPTY
npm error syscall rename
npm error path /home/you/.nvm/versions/node/v22.13.1/lib/node_modules/@anthropic-ai/claude-code
npm error dest /home/you/.nvm/versions/node/v22.13.1/lib/node_modules/@anthropic-ai/.claude-code-tVWAnUUt
npm error errno -39
npm error ENOTEMPTY: directory not empty, rename '...'

La riga npm error path indica la directory che npm non è riuscito a spostare. Elimina quella directory e qualsiasi directory .claude-code-* rimasta accanto ad essa, che esecuzioni interrotte in precedenza possono lasciare. I comandi seguenti trovano la tua directory globale dei pacchetti con npm root -g; se la directory indicata dalla riga npm error path non si trova sotto la directory stampata da npm root -g, ad esempio perché hai cambiato versione di Node con nvm, elimina invece le directory indicate dall'errore:

[tab] macOS/Linux

rm -rf "$(npm root -g)/@anthropic-ai/claude-code"

Quindi rimuovi eventuali directory temporanee rimaste. Se Zsh stampa no matches found, non ce n'erano da rimuovere:

rm -rf "$(npm root -g)/@anthropic-ai/.claude-code-"*

[tab] Windows PowerShell

Remove-Item -Recurse -Force "$(npm root -g)/@anthropic-ai/claude-code", "$(npm root -g)/@anthropic-ai/.claude-code-*"

Quindi reinstalla. Su npm 12, segui Correggere un'installazione con npm 12. Altrimenti, esegui:

npm install -g @anthropic-ai/claude-code

Verifica con claude --version, che stampa un numero di versione come 2.1.211 (Claude Code).

Accesso e autenticazione

Queste sezioni trattano errori di accesso, errori OAuth e problemi con i token.

Reimposta l'accesso

Quando l'accesso non riesce e la causa non è chiara, una nuova autenticazione pulita risolve la maggior parte dei casi:

1. Esegui /logout per uscire completamente
2. Chiudi Claude Code
3. Riavvia con claude e completa di nuovo il processo di autenticazione

Se il browser non si apre automaticamente durante l'accesso, premi c per copiare l'URL OAuth negli appunti, quindi incollalo manualmente in un browser. Questo funziona anche quando l'URL va a capo su più righe in un terminale stretto o SSH e non può essere cliccato direttamente.

OAuth error: Invalid code

Se vedi OAuth error: Invalid code. Please make sure the full code was copied, il codice di accesso è scaduto o è stato troncato durante il copia-incolla.

Soluzioni:

• Premi Enter per riprovare e completa rapidamente l'accesso dopo l'apertura del browser
• Digita c per copiare l'URL completo se il browser non si apre automaticamente
• Se usi una sessione remota/SSH, il browser potrebbe aprirsi sulla macchina sbagliata. Copia invece l'URL visualizzato nel terminale e aprilo nel tuo browser locale.

403 Forbidden dopo l'accesso

Se vedi API Error: 403 Request not allowed dopo aver effettuato l'accesso:

• Utenti Claude Pro/Max/Ultra: verifica che il tuo abbonamento sia attivo su claude.ai/settings
• Utenti di Anthropic Console: conferma che il tuo account abbia il ruolo "Claude Code" o "Developer". Gli amministratori lo assegnano nella pagina Members della Console su platform.claude.com/settings/members.
• Dietro un proxy: i proxy aziendali possono interferire con le richieste API. Consulta configurazione di rete per la configurazione del proxy.

Claude Code access has not been granted for this account

Se la pagina di accesso mostra Authorization failed con il messaggio Claude Code access has not been granted for this account. Contact your administrator. dopo che hai effettuato l'accesso da Claude Code, la tua organizzazione Claude Enterprise ha impostato il tuo ruolo su Custom e nessuno dei ruoli personalizzati assegnati ai tuoi gruppi concede Claude Code. Con il ruolo Custom, ottieni l'accesso solo da quei ruoli personalizzati, quindi nulla di ciò che modifichi in Claude Code risolve questo errore.

Per ottenere l'accesso:

1. Chiedi a un Owner della tua organizzazione Claude di assegnare a uno dei tuoi gruppi un ruolo personalizzato che conceda l'accesso a Claude Code, oppure di cambiare il tuo ruolo da Custom a un ruolo standard come User. Gli Owner gestiscono i ruoli nelle impostazioni dei ruoli dell'organizzazione.
2. Dopo che l'Owner ha apportato la modifica, esegui claude e accedi di nuovo.

This organization has been disabled con un abbonamento attivo

Se vedi API Error: 400 ... "This organization has been disabled" nonostante tu abbia un abbonamento Claude attivo, una variabile d'ambiente ANTHROPIC_API_KEY sta sovrascrivendo il tuo abbonamento. Questo accade comunemente quando una vecchia chiave API di un precedente datore di lavoro o progetto è ancora impostata nel profilo della tua shell.

Quando ANTHROPIC_API_KEY è presente e l'hai approvata, Claude Code usa quella chiave invece delle credenziali OAuth del tuo abbonamento. In modalità non interattiva con il flag -p, la chiave viene sempre usata quando è presente. Consulta precedenza dell'autenticazione per l'ordine di risoluzione completo.

Per usare invece il tuo abbonamento, rimuovi l'impostazione della variabile d'ambiente ed eliminala dal profilo della tua shell:

[tab] macOS/Linux

unset ANTHROPIC_API_KEY
claude

[tab] Windows PowerShell

Remove-Item Env:ANTHROPIC_API_KEY
claude

Controlla ~/.zshrc, ~/.bashrc o ~/.profile per righe export ANTHROPIC_API_KEY=... e rimuovile per rendere permanente la modifica. Su Windows, controlla il tuo profilo PowerShell in $PROFILE e le variabili d'ambiente utente per ANTHROPIC_API_KEY. Esegui /status all'interno di Claude Code per confermare quale metodo di autenticazione è attivo.

L'accesso OAuth non riesce in WSL2, SSH o container

Se non si apre alcun browser, oppure il browser ti fa accedere e poi mostra un errore di connessione per un indirizzo localhost, puoi completare l'accesso senza risolvere nessuno dei due problemi. Accedi invece tramite l'URL di accesso separato che il terminale mostra sopra il suo prompt di incolla:

1. Copia l'URL di accesso

Al prompt di accesso interattivo, premi c per copiare l'URL, oppure selezionalo nel terminale. Con claude auth login, copia l'URL che stampa.

2. Accedi tramite quell'URL

Apri l'URL in un browser sulla tua macchina locale e accedi. Il browser mostra quindi un codice invece di tornare a localhost.

3. Incolla il codice

Incolla quel codice nel terminale al prompt che inizia con Paste code here.

Se incollare il codice nel prompt interattivo non ha alcun effetto, probabilmente la scorciatoia di incolla del tuo terminale non raggiunge il campo di input. Prova la scorciatoia di incolla alternativa del tuo terminale, spesso il clic destro o Shift+Insert in Windows Terminal, oppure usa invece claude auth login, che legge il codice incollato dallo standard input:

claude auth login

Questo fallback si applica anche su Windows nativo o in qualsiasi terminale in cui incollare nel prompt interattivo non funziona.

Su WSL2, se non si è aperto alcun browser, puoi anche permettere a Claude Code di aprire il tuo browser Windows la volta successiva impostando la variabile d'ambiente BROWSER sul percorso di quel browser:

export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
claude

Accesso non effettuato o token scaduto

Se Claude Code ti chiede di accedere di nuovo dopo una sessione, il tuo token OAuth potrebbe essere scaduto.

Esegui /login per autenticarti di nuovo. Se questo accade spesso, verifica che l'orologio di sistema sia preciso, poiché la convalida dei token dipende da timestamp corretti.

Le sessioni parallele su una stessa macchina condividono un accesso salvato e ne coordinano il rinnovo in modo che un solo processo alla volta aggiorni il token. Per sapere cosa fanno le altre sessioni dopo che accedi di nuovo in una di esse, consulta Not logged in.

Prima della v2.1.211, riattivare la macchina dalla sospensione poteva far sì che due sessioni eseguissero il rinnovo con lo stesso token, il che revocava l'accesso salvato e chiedeva a tutte le sessioni aperte di accedere di nuovo contemporaneamente.

Su macOS, Claude Code salva le credenziali nel Keychain login. Quando il Keychain rifiuta la scrittura, ad esempio quando è bloccato in una sessione SSH o la sua password non è sincronizzata con la password del tuo account, Claude Code salva invece il tuo accesso nel file in chiaro ~/.claude/.credentials.json. Un accesso alla Console che crea una chiave API non riesce finché il Keychain non è di nuovo scrivibile.

Per rendere di nuovo scrivibile il Keychain e riportare il tuo accesso nel Keychain crittografato:

1. Verifica l'accesso al Keychain

Esegui claude doctor per verificare l'accesso al Keychain. Quando il Keychain rifiuta le scritture, il report elenca un avviso che inizia con macOS Keychain is not writable, seguito da una correzione suggerita. Quando il report non elenca alcun avviso relativo al Keychain, il Keychain è scrivibile e puoi passare direttamente all'ultimo passaggio.

2. Sblocca il Keychain

security unlock-keychain ~/Library/Keychains/login.keychain-db

Inserisci la password del Keychain quando il comando la richiede, quindi esegui di nuovo claude doctor. Se lo sblocco ha funzionato, il report non elenca più l'avviso relativo al Keychain.

3. Risincronizza la password del Keychain se lo sblocco non aiuta

Apri Accesso Portachiavi, seleziona il portachiavi login e scegli Edit > Change Password for Keychain "login" per risincronizzarlo con la password del tuo account. Quindi esegui di nuovo claude doctor. Passa al passaggio successivo quando il report non elenca più l'avviso relativo al Keychain.

4. Esci e accedi di nuovo

Una volta che il Keychain è di nuovo scrivibile, Claude Code vi riporta le credenziali la prossima volta che scrive una credenziale. Per forzarlo subito, esegui /logout e poi /login. L'uscita rimuove tutte le credenziali memorizzate, inclusi il contenuto del file in chiaro, gli accessi salvati ai server MCP e i valori sensibili dei plugin, quindi dovrai autorizzare di nuovo i server MCP e reinserire i segreti dei plugin. Accedendo di nuovo, il tuo accesso viene memorizzato nel Keychain.

L'accesso non riesce su una directory home di rete

Quando una richiesta non riesce con API Error: 401 e la tua directory di configurazione si trova su un filesystem di rete, verifica se quel filesystem o la tua quota su di esso è pieno. Senza spazio disponibile, Claude Code non può salvare un accesso nuovo o rinnovato nel file .credentials.json in chiaro, e claude auth login può comunque stampare Login successful.

1. Libera spazio sul filesystem

Elimina i file che non ti servono più sul filesystem che contiene ~/.claude, o la directory che hai impostato in CLAUDE_CONFIG_DIR.

2. Accedi di nuovo

Esegui /login al prompt di Claude Code oppure claude auth login nella tua shell.

Prima della v2.1.318, quando Claude Code salvava il file di accesso su un filesystem di rete pieno, poteva sostituire un accesso memorizzato ancora valido con un file vuoto. I comandi successivi segnalavano quindi Not logged in.

Le credenziali di Bedrock, Agent Platform o Foundry non vengono caricate

Se hai configurato Claude Code per usare un provider cloud e vedi Could not load credentials from any providers su Amazon Bedrock, Could not load the default credentials su Agent Platform di Google Cloud, oppure ChainedTokenCredential authentication failed su Microsoft Foundry, probabilmente la CLI del tuo provider cloud non è autenticata nella shell corrente.

Per Amazon Bedrock, conferma che le tue credenziali AWS siano valide:

aws sts get-caller-identity

Per Agent Platform di Google Cloud, conferma che ANTHROPIC_VERTEX_PROJECT_ID e CLOUD_ML_REGION siano impostate nella tua shell, quindi imposta le credenziali predefinite dell'applicazione:

gcloud auth application-default login

Per Microsoft Foundry, conferma che ANTHROPIC_FOUNDRY_API_KEY sia impostata, oppure accedi con la Azure CLI in modo che la catena di credenziali predefinita possa trovare il tuo account:

az login

Se le credenziali funzionano nel tuo terminale ma non nell'estensione VS Code o JetBrains, probabilmente il processo dell'IDE non ha ereditato l'ambiente della tua shell. Imposta le variabili d'ambiente del provider nelle impostazioni dell'IDE stesso, oppure avvia l'IDE da un terminale in cui sono già esportate.

Consulta Amazon Bedrock, Agent Platform di Google Cloud o Microsoft Foundry per la configurazione completa del provider.

Ancora bloccato

Se nessuno dei precedenti risolve il tuo problema:

1. Controlla il repository GitHub per i problemi noti, o apri uno nuovo con il tuo sistema operativo, il comando di installazione che hai eseguito, e l'output di errore completo
2. Se claude --version funziona ma qualcos'altro non va, esegui claude doctor per un rapporto diagnostico automatizzato
3. Se riesci ad avviare una sessione, usa /feedback all'interno di Claude Code per segnalare il problema
4. Se il problema riguarda il tuo account piuttosto che l'installazione, come un ciclo di accesso, un abbonamento non riconosciuto, o un'organizzazione disabilitata, contatta il supporto di Anthropic: accedi a claude.ai (utenti Console: platform.claude.com), fai clic sulle tue iniziali in basso a sinistra, e seleziona Ottieni aiuto. Vedi Come ottenere supporto per il flusso completo.