Riferimento degli errori

Consulta i messaggi di errore di runtime di Claude Code con il significato di ciascuno e come risolverli.

Questa pagina elenca gli errori di runtime che Claude Code visualizza e come recuperare da ciascuno, oltre a cosa controllare quando le risposte sembrano non corrette senza un errore. Per gli errori di installazione come command not found o errori TLS durante la configurazione, vedi Risoluzione dei problemi di installazione e accesso.

Ad eccezione degli errori di Wrapper e IDE, che il programma di avvio stampa piuttosto che Claude Code stesso, questi errori e i comandi di recupero si applicano su CLI, l'app Desktop e le sessioni cloud, poiché tutti e tre avvolgono lo stesso CLI di Claude Code. Per altri problemi specifici della superficie, vedi la sezione di risoluzione dei problemi nella pagina di quella superficie.

Trova il tuo errore

Abbina il messaggio che vedi a una sezione qui sotto.

Tentativi automatici

Claude Code ritenta i guasti transitori fino a 10 volte con backoff esponenziale prima di mostrarti un errore. Non sempre ritenta un guasto che arriva a metà della risposta di Claude. Quando vedi uno degli errori in questa pagina, Claude Code ha già effettuato i tentativi che si applicano a quel guasto.

Claude Code ritenta questi guasti:

• Errori del server, risposte sovraccariche e timeout delle richieste che arrivano prima che una qualsiasi risposta di Claude sia stata trasmessa.
• Un errore del server o una risposta sovraccarica che arriva dopo che Claude ha finito di pensare ma prima di aver iniziato un testo o una chiamata a uno strumento. Claude Code ritenta un errore del server a quel punto fino a due volte. Prima della v2.1.284, Claude Code terminava il turno con l'errore a quel punto.
• Connessioni interrotte. Quando una connessione si interrompe a metà di una richiesta prima che Claude abbia completato una qualsiasi parte della sua risposta, incluso il suo ragionamento, Claude Code invia nuovamente la richiesta con lo stesso backoff e il turno continua, anche se del testo aveva già iniziato a essere trasmesso. Quando si interrompe dopo che Claude ha finito di pensare ma prima di aver iniziato un testo o una chiamata a uno strumento, Claude Code invece invia nuovamente la richiesta fino a due volte in rapida successione, e termina il turno con Connection lost before a response was produced se la connessione continua a interrompersi a quel punto.
• Una connessione che Claude Code rileva è stata interrotta dal tuo computer che si è addormentato a metà di una richiesta. Claude Code la conta come una connessione interrotta secondo le regole sopra; una volta che l'etichetta di riprovazione nomina il motivo specifico, legge Connection lost while your computer was asleep, e se il turno termina dopo che Claude ha finito di pensare ma prima di un testo o di una chiamata a uno strumento, il messaggio legge Your computer went to sleep before a response was produced.
• Un flusso di risposta bloccato, quando le intestazioni di risposta sono arrivate ma nessuna risposta di Claude è arrivata, o quando Claude ha finito di pensare ma non ha iniziato un testo o una chiamata a uno strumento: Claude Code interrompe la connessione bloccata e invia nuovamente la richiesta al massimo una volta, al di fuori del budget di 10 tentativi sopra. Se la risposta si blocca una seconda volta dopo che Claude ha finito di pensare ma prima di un testo o di una chiamata a uno strumento, Claude Code termina il turno con The response stalled before a response was produced.
• Una richiesta di streaming a cui l'API non risponde mai con intestazioni di risposta, su una connessione dove il first-byte deadline runs: Claude Code la interrompe alla scadenza e la invia nuovamente al massimo una volta per richiesta di modello, entro il budget di riprovazione, quindi termina il turno con No response from API se anche quel tentativo rimane senza risposta. Su altre connessioni, la richiesta attende API_TIMEOUT_MS. Quando imposti CLAUDE_CODE_RETRY_WATCHDOG, il limite di un tentativo non si applica.
• Throttle 429 temporanei, ma non il 429 del limite di spesa di un gateway, che non è un throttle; vedi Spend limit reached.
  • Quando sei connesso con un abbonamento claude.ai, questo include throttle 429 che non portano le intestazioni di quota del tuo piano. Prima della v2.1.199, Claude Code ritentava questi throttle solo per le chiavi API e gli accessi Enterprise.
• Una richiesta rifiutata perché l'input più max_tokens supera il limite di contesto. Inviarla nuovamente invariata fallirebbe allo stesso modo, quindi Claude Code ritenta con un max_tokens ridotto, e smette di ritentare e compatta invece in due casi:
  • Quando nessuna riduzione può adattarsi, ad esempio quando la conversazione stessa riempie quasi la finestra di contesto.
  • Quando un tentativo non può ridurre ulteriormente max_tokens. Prima della v2.1.218, Claude Code poteva inviare nuovamente una richiesta ridotta che ancora non si adattava, ad esempio quando il budget di ragionamento esteso superava il contesto rimanente, fino a quando il budget di riprovazione non si esauriva.
• Una credenziale Google Cloud scaduta o mancante su Google Cloud's Agent Platform, o credenziali AWS che non riescono a caricarsi sulla tua macchina. Claude Code scarta le sue credenziali memorizzate nella cache e ritenta fino a due volte, quindi segnala l'errore in modo che tu possa autenticarti di nuovo subito, come descritto in Could not load AWS or Google Cloud credentials. Prima della v2.1.228, Claude Code ritentava una credenziale Google Cloud non riuscita attraverso il budget di riprovazione completo prima di mostrare l'errore.
• Un 401 o 403 dall'API Anthropic, direttamente o attraverso un LLM gateway, mentre uno script apiKeyHelper fornisce la credenziale. Claude Code esegue nuovamente lo script e ritenta con il suo output aggiornato, entro il budget di riprovazione completo. Quando lo script stesso fallisce al nuovo tentativo, Claude Code mostra Your apiKeyHelper script is failing invece.

Prima della v2.1.227, Connection lost before a response was produced leggeva Connection closed while thinking, before producing a response e The response stalled before a response was produced leggeva Response stalled while thinking, before producing a response.

Claude Code non ritenta questi guasti:

• Un errore di convalida del certificato TLS, come un proxy che ispeziona TLS, un bundle NODE_EXTRA_CA_CERTS mancante, o un certificato scaduto. Claude Code segnala l'errore al primo tentativo, in modo che tu possa correggere subito la configurazione del certificato; vedi SSL certificate errors. Claude Code ritenta comunque condizioni TLS transitorie come un timeout di handshake. Prima della v2.1.199, Claude Code ritentava i guasti dei certificati attraverso il budget di riprovazione completo prima di mostrare l'errore.
• Un errore del server, una connessione interrotta, o un flusso bloccato che arriva dopo che Claude ha completato un blocco di testo o una chiamata a uno strumento, o ne ha iniziato uno dopo aver finito il suo ragionamento, ma prima di finire la risposta. Claude Code non esegue nuovamente la richiesta, perché ciò potrebbe eseguire le stesse chiamate agli strumenti due volte. Mantiene ciò che Claude ha completato, esegue le chiamate agli strumenti che Claude ha finito, e continua il turno dai loro risultati. Per ciò che vedi in una sessione interattiva e in una non interattiva, leggi The response above may be incomplete. Prima della v2.1.199, Claude Code scartava l'output parziale e segnalava l'intero turno come un errore quando un errore del server arrivava a metà del flusso.
• Un guasto che arriva dopo che Claude ha finito la risposta: non c'è nulla da ritentare, quindi Claude Code mantiene la risposta completa e termina il turno normalmente.
• Una Amazon Bedrock streaming response with an unexpected content-type, perché il gateway o il proxy che riscrive la risposta riscriverebbero il tentativo allo stesso modo. Richiede Claude Code v2.1.208 o successivo.
• Un tentativo non in streaming di una richiesta in streaming non riuscita che ottiene uno stato di successo ma no Claude API message in the body. Claude Code termina il turno con quell'errore.
• Una richiesta che il controllo della politica della tua organizzazione ha negato, che emerge come una riga API Error: che porta il messaggio di negazione. Gli amministratori della tua organizzazione hanno configurato il controllo con Inference hooks, una funzione Claude Enterprise, e il messaggio termina con le istruzioni che hanno configurato, o per impostazione predefinita ti dice di contattarli. Claude Code non invia nuovamente la richiesta negata allo stesso modello o a un fallback model, perché il diniego riguarda il contenuto della richiesta piuttosto che il modello. Prima della v2.1.239, Claude Code poteva inviare nuovamente una richiesta negata, senza streaming o su un fallback model configurato, prima di mostrarti il diniego.

Cosa vedi mentre Claude Code ritenta o attende

Durante il tentativo, lo spinner mostra un countdown Retrying in Ns · attempt x/y dopo un'etichetta di errore. L'etichetta nomina il motivo specifico dal primo tentativo per i guasti su cui puoi agire subito: la rete è inattiva, un handshake TLS non è riuscito, o hai raggiunto un rate limit. Per altri errori legge API error all'inizio. A partire dalla v2.1.198 passa al motivo specifico dal terzo tentativo, o al tentativo finale quando CLAUDE_CODE_MAX_RETRIES consente meno di tre; le versioni precedenti passano solo al tentativo finale.

A partire dalla v2.1.198, il suggerimento dello spinner usuale è soppresso durante i tentativi. Una volta rivelato il motivo dell'errore, se il guasto è un sovraccarico 529 la riga sotto il countdown nomina anche dove controllare lo stato del servizio: status.claude.com sull'API Anthropic, o l'host del provider o del gateway nominato nel messaggio su altre configurazioni.

Se nessun dato arriva sul flusso di risposta per 20 secondi mentre una richiesta è ancora in sospeso, lo spinner mostra Waiting for API response · will retry in … · check your network prima che sia iniziato un tentativo. La richiesta non è ancora fallita: il countdown corre fino al punto in cui Claude Code interrompe la connessione bloccata. Dopo l'interruzione, ciò che vedi dipende da quanto lontano era arrivata la risposta:

• Prima che Claude abbia completato un blocco di testo o una chiamata a uno strumento, o ne abbia iniziato uno dopo aver finito il suo ragionamento, Claude Code ritenta la richiesta o termina il turno con un errore. Automatic retries dice quali blocchi ritenta e quante volte.
• Dopo che Claude ha completato un blocco di testo o una chiamata a uno strumento, o ne ha iniziato uno dopo aver finito il suo ragionamento, ma prima che Claude abbia finito la risposta, Claude Code mantiene ciò che Claude ha completato, continua il turno da qualsiasi chiamata a uno strumento che Claude ha finito, e mostra The response above may be incomplete. In una sessione non interattiva, e per la risposta di un subagent in qualsiasi sessione, Claude Code potrebbe prima chiedere a Claude di continuare la risposta; quella voce dice quando lo fa e quando vedi ancora l'avviso lì.
• Dopo che Claude ha finito la risposta, Claude Code termina il turno normalmente.

Il banner si cancella da solo una volta che i dati riprendono o un tentativo ha successo. Se riappare ad ogni tentativo, trattalo come un network issue. Prima della v2.1.185, il banner appariva dopo 10 secondi con una formulazione diversa.

Mentre Claude sta consultando l'advisor, il banner appare dopo 90 secondi senza dati invece di 20, perché una lunga revisione dell'advisor può non inviare nulla per ben oltre 20 secondi. Prima della v2.1.214, la soglia di 20 secondi si applicava anche durante le chiamate dell'advisor, quindi il banner appariva durante le revisioni dell'advisor anche quando non c'era nulla di sbagliato.

Sintonizza il comportamento dei tentativi

Puoi sintonizzare il comportamento dei tentativi con queste variabili d'ambiente:

Errori del server

La maggior parte di questi errori proviene dal provider di inferenza: il servizio di Anthropic su Anthropic API e il servizio dietro l'endpoint di quel provider su Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry o un gateway personalizzato. Auto mode cannot determine the safety of an action e Agent terminated early due to an API error coprono anche cause dal tuo lato, come un account Amazon Bedrock che non può invocare il modello del classificatore o un subagent che ha raggiunto un limite di utilizzo.

API Error: 500 Internal server error

Claude Code mostra il codice di stato e il messaggio di errore dell'API per qualsiasi risposta 5xx. L'esempio seguente mostra una risposta 500 su Anthropic API:

API Error: 500 Internal server error. This is a server-side issue, usually temporary — try again in a moment. If it persists, check https://status.claude.com.

La frase finale indica dove controllare lo stato del servizio e varia in base al provider. Le configurazioni di Amazon Bedrock, Google Cloud's Agent Platform e Microsoft Foundry indicano lo stato del servizio di quel provider. Un ANTHROPIC_BASE_URL personalizzato indica l'host del gateway.

Un 5xx dall'API stessa indica un errore imprevisto all'interno dell'API. Non è causato dal tuo prompt, dalle tue impostazioni o dal tuo account.

Quando un proxy, un load balancer o un gateway risponde con una pagina di errore HTML, il messaggio mostra il codice di stato e il titolo della pagina, come API Error: 502 Bad Gateway. Per una pagina senza titolo, il messaggio mostra invece il codice di stato e il suo nome standard. Prima della v2.1.281, il codice di stato veniva omesso quando la pagina aveva un titolo e il markup grezzo della pagina veniva stampato quando non ne aveva uno.

Cosa fare:

• Controlla status.claude.com o la pagina di stato del provider indicata nel messaggio per eventuali incidenti in corso
• Aspetta un minuto, quindi invia di nuovo il messaggio. Il tuo messaggio originale è ancora nella conversazione, quindi per un prompt lungo puoi digitare try again invece di incollarlo tutto.
• Se l'errore persiste senza alcun incidente pubblicato, esegui /feedback in modo che Anthropic possa indagare con i dettagli della tua richiesta. Consulta Segnalare un errore se /feedback non è disponibile nel tuo ambiente.

API Error: Repeated 529 Overloaded errors

L'API è temporaneamente al limite della capacità per tutti gli utenti. Claude Code ha già riprovato più volte prima di mostrare questo messaggio:

API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.

La frase finale varia in base al provider nello stesso modo dell'errore 500 descritto sopra.

Un 529 non è il tuo limite di utilizzo e non viene conteggiato nella tua quota.

Cosa fare:

• Controlla status.claude.com o la pagina di stato del provider indicata nel messaggio per eventuali avvisi sulla capacità

• Riprova tra qualche minuto

• Esegui /model e passa a un modello diverso per continuare a lavorare, poiché la capacità è monitorata per modello. Claude Code ti chiede di farlo quando un modello è sotto un carico particolarmente elevato, ad esempio Opus is experiencing high load, please use /model to switch to Sonnet. Sui modelli Fable il messaggio indica Fable.

  In una sessione eseguita dall'app Claude Desktop, come la scheda Code o Cowork, il messaggio è Opus is experiencing high load. Switch to Sonnet. e cambi modello con il selettore di modelli dell'app.

Request timed out

L'API non ha risposto entro la scadenza della connessione.

Request timed out

Questo può accadere durante periodi di carico elevato o quando il modello sta generando una risposta molto lunga. Il timeout predefinito della richiesta è di 10 minuti.

Cosa fare:

• Riprova la richiesta
• Se la causa è una rete lenta o un proxy, aumenta API_TIMEOUT_MS come descritto in Nuovi tentativi automatici
• Se i timeout sono frequenti e la tua rete per il resto funziona correttamente, consulta Errori di rete e di connessione più avanti

No response from API

Claude Code ha inviato una richiesta in streaming e l'API non ha restituito intestazioni di risposta entro la scadenza per il primo byte, quindi Claude Code ha interrotto la richiesta invece di attendere l'intero timeout di richiesta API_TIMEOUT_MS, 10 minuti per impostazione predefinita. Claude Code invia di nuovo la richiesta al massimo una volta, se il budget dei nuovi tentativi lo consente. Quando anche il nuovo tentativo resta senza risposta, il turno termina con questo messaggio, che mostra quanto ha atteso ciascun tentativo. Quando imposti CLAUDE_CODE_RETRY_WATCHDOG, il limite di un solo nuovo tentativo non si applica e Claude Code riprova secondo il budget descritto in Regolare il comportamento dei nuovi tentativi.

API Error: No response from API (waited 3m, then 10m on the retry). If a proxy or gateway on your network holds responses until they complete, raise API_TIMEOUT_MS or CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS to wait longer.

Claude Code imposta separatamente l'attesa delle intestazioni di risposta per il primo tentativo e l'attesa per il nuovo tentativo:

• Primo tentativo: CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS quando lo imposti su 1 o più, limitato a un valore compreso tra 10 secondi e 30 minuti. Altrimenti Claude Code usa il timeout del watchdog a livello di byte indicato in Watchdog di inattività dello streaming, quindi le variabili che modificano quel timeout modificano anche questa attesa. In entrambi i casi, Claude Code aggiunge un secondo per ogni 32KB del corpo della richiesta.
• Nuovo tentativo: un secondo in meno di API_TIMEOUT_MS, poco meno di 10 minuti per impostazione predefinita, in modo che il nuovo tentativo possa durare più a lungo di un proxy o gateway che trattiene la risposta fino al completamento della generazione. Su Amazon Bedrock, il nuovo tentativo usa la stessa scadenza del primo tentativo e il messaggio mostra una sola durata invece di due.

Nessuna delle due attese supera un secondo in meno di un API_TIMEOUT_MS positivo, e un API_TIMEOUT_MS positivo inferiore a 11 secondi disattiva la scadenza. Il watchdog a livello di byte parte solo quando arrivano le intestazioni di risposta, quindi una risposta che smette di inviare byte dopo quel momento segue le regole per i flussi bloccati invece di questa scadenza.

Cosa fare:

• Invia di nuovo il messaggio. Il tuo messaggio originale è ancora nella conversazione, quindi per un prompt lungo puoi digitare try again invece di incollarlo tutto.
• Se si ripete, trattalo come un problema di rete o di proxy.
• Se un proxy o gateway sulla tua rete trattiene le risposte fino al loro completamento, aumenta API_TIMEOUT_MS in modo che il nuovo tentativo attenda più a lungo. Su Amazon Bedrock, aumenta anche CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS.
• Se il primo tentativo continua ad andare in timeout e poi il nuovo tentativo riesce, aumenta CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS in modo che anche il primo tentativo attenda abbastanza a lungo.

Prima della v2.1.242, Claude Code attendeva l'intero timeout di richiesta API_TIMEOUT_MS, 10 minuti per impostazione predefinita, prima di far fallire una richiesta in streaming senza risposta. Prima della v2.1.261, il nuovo tentativo attendeva la stessa scadenza del primo tentativo e il messaggio non mostrava alcuna durata.

The response above may be incomplete

Una richiesta in streaming non è riuscita mentre la risposta era ancora in corso, dopo che Claude aveva completato un blocco di testo o una chiamata a uno strumento, oppure ne aveva iniziato uno dopo aver terminato il ragionamento. Inviare di nuovo la richiesta potrebbe eseguire due volte le stesse chiamate agli strumenti, quindi Claude Code conserva l'output che Claude ha completato e aggiunge questo avviso invece di scartare il turno. La variante che vedi indica la causa:

API Error: Server error mid-response. The response above may be incomplete.
API Error: Connection lost mid-response. The response above may be incomplete.
API Error: Your computer went to sleep mid-response. The response above may be incomplete.
API Error: The response stopped arriving. The response above may be incomplete.
API Error: Part of the response never arrived. The response above may be incomplete.
API Error: The response stream was malformed. The response above may be incomplete.

• Server error mid-response: un errore di sovraccarico o un errore del server 5xx a metà flusso. Questa variante richiede Claude Code v2.1.199 o successivo; prima di allora, in questo caso l'output parziale veniva scartato e l'intero turno veniva segnalato come errore.
• Connection lost mid-response: la connessione si è interrotta. Vedi questa variante anche quando un proxy o gateway chiude regolarmente il corpo della risposta prima che la risposta sia terminata.
• Your computer went to sleep mid-response: Claude Code ha rilevato che il tuo computer è entrato in sospensione mentre la risposta era in streaming. Quando il computer si riattiva, Claude Code considera la connessione interrotta e smette di leggerla.
• Part of the response never arrived: un evento del flusso è andato perso tra l'API e Claude Code, quindi un evento successivo ha fatto riferimento a contenuto mai arrivato. Prima della v2.1.281, questo caso terminava il turno con API Error: Content block not found.
• The response stream was malformed: è arrivato un evento per un blocco di contenuto già terminato, oppure è arrivato un evento danneggiato. Un evento danneggiato è un evento i cui dati non sono JSON valido, il cui contenuto manca o il cui contenuto non corrisponde al tipo dell'evento. Prima della v2.1.284, quando un evento con JSON non valido arrivava dopo che Claude aveva completato il ragionamento, un blocco di testo o una chiamata a uno strumento, veniva invece mostrato l'errore grezzo del parser, ad esempio uno che inizia con API Error: JSON Parse error.
• The response stopped arriving: la connessione è rimasta aperta ma ha smesso di trasmettere dati, quindi il watchdog di inattività dello streaming l'ha interrotta. Prima della v2.1.222, Claude Code poteva segnalare questo errore anche sulle connessioni gateway raggiunte tramite ANTHROPIC_BASE_URL o ANTHROPIC_AWS_BASE_URL mentre i ping keep-alive del server continuavano ad arrivare, perché su quelle connessioni contava solo gli eventi di risposta analizzati; l'aggiornamento elimina quei timeout spuri su quei percorsi. I gateway raggiunti tramite un URL di base del provider come ANTHROPIC_BEDROCK_BASE_URL non sono coperti dal watchdog a livello di byte; consulta Watchdog di inattività dello streaming.

Prima della v2.1.227, Connection lost mid-response era Connection closed mid-response e The response stopped arriving era Response stalled mid-stream.

Quando un evento del flusso perso, duplicato o danneggiato arriva prima che Claude abbia iniziato qualsiasi testo o chiamata a uno strumento, non vedi questo avviso:

• Se Claude aveva completato solo il ragionamento, Claude Code invia di nuovo la richiesta. Quando i flussi inviati di nuovo si interrompono allo stesso modo, il turno termina con Part of the response never arrived and no response was produced. Try again. o The response stream was malformed and no response was produced. Try again.
• Se non era stato completato nulla, Claude Code invia invece di nuovo la richiesta senza streaming. Se hai disattivato quel fallback con CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK, il turno termina con API Error: Content block not found per un evento perso o con API Error: Content block already closed per un evento duplicato. Per un evento danneggiato con il fallback disattivato, il turno termina con API Error: Stream event unreadable o con l'errore grezzo del parser.

In quattro casi, Claude Code gestisce l'errore senza mostrare subito questo avviso:

• Nelle fasi iniziali della risposta, Claude Code riprova dopo l'errore oppure termina il turno con un errore diverso. Consulta Nuovi tentativi automatici.
• Quando uno di questi errori arriva dopo che Claude ha terminato la risposta, Claude Code conserva la risposta completa e termina il turno normalmente, senza questo avviso. Prima della v2.1.222, Claude Code mostrava questo avviso quando la connessione si interrompeva o si bloccava dopo il completamento della risposta e segnalava il turno come errore anche se la risposta era completa.
• In una sessione non interattiva, come un'esecuzione -p, un'esecuzione dell'Agent SDK o una sessione cloud, non devi inviare tu continue quando la risposta interrotta si trova nella conversazione principale e contiene testo ma nessuna chiamata a uno strumento: Claude Code conserva l'output parziale e chiede a Claude di continuare da dove si era fermato, fino a tre volte di seguito. Vedi questo avviso per una risposta di questo tipo solo quando Claude Code ha esaurito quelle continuazioni. Prima della v2.1.246, Claude Code terminava un turno non interattivo con questo avviso alla prima interruzione.
• In un subagent, che la sessione sia interattiva o meno: quando la sua risposta interrotta contiene testo ma nessuna chiamata a uno strumento, Claude Code chiede al subagent di continuare. L'avviso diventa l'ultimo messaggio del subagent solo quando quelle continuazioni sono esaurite. Prima della v2.1.257, un subagent mostrava questo avviso alla prima interruzione.

Cosa fare:

• In una sessione interattiva, leggi la risposta che rimane sullo schermo: Claude Code conserva ogni blocco che Claude ha completato prima dell'errore, ma scarta un blocco finale interrotto quando il turno termina, quindi le frasi finali o le chiamate agli strumenti finali potrebbero mancare. Rispondi con continue per far riprendere Claude dal suo ultimo blocco completato.
• In modalità non interattiva (-p):
  • Con l'output di testo predefinito, Claude Code stampa l'ultimo blocco di testo completato che conserva ancora da un punto precedente del turno, seguito da questo messaggio. Quando non ne conserva nessuno, Claude Code stampa solo questo messaggio, ad esempio perché ha compattato la conversazione a metà turno e ha eliminato quel testo. Prima della v2.1.219, Claude Code stampava solo questo messaggio nell'output di testo di -p e scartava la risposta già prodotta.
  • Con --output-format json o stream-json, Claude Code riporta questo messaggio nel campo result.
  • Per continuare il turno quando la connessione è stabile, riprendi la sessione e invia continue come descritto in Continuare le conversazioni.

Auto mode cannot determine the safety of an action

Il modello che la modalità auto usa per classificare le azioni non è riuscito a produrre una decisione, quindi la modalità auto non ha approvato automaticamente l'azione. Il messaggio che vedi dipende da come il classificatore non è riuscito.

Le letture, le ricerche e le modifiche all'interno della tua directory di lavoro non passano dal classificatore, quindi continuano a funzionare in tutti questi casi.

Quando il modello del classificatore non è disponibile:

<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now. Wait a moment and then try this action again.

Quando Claude Code riesce a determinare la categoria dell'errore, la indica tra parentesi dopo temporarily unavailable, ad esempio <model> is temporarily unavailable (rate-limited), so auto mode cannot determine the safety of <tool> right now. Le categorie sono (rate-limited), (overloaded), (server error), (timed out) e (connection failed). Se (timed out) o (connection failed) si ripete, controlla la tua connessione; consulta Unable to connect to API. Prima della v2.1.229, il messaggio non indicava mai una categoria e diceva Wait briefly and then try this action again.

Quando nessuna categoria è adatta, il messaggio appare senza categoria tra parentesi; più errori diversi producono questa forma. Su Amazon Bedrock, incluso l'endpoint Mantle, appare anche quando il tuo account AWS non può invocare il modello indicato nel messaggio, e quell'errore si ripete a ogni nuovo tentativo finché al tuo account non viene concesso l'accesso al modello.

Cosa fare:

• Riprova dopo qualche secondo; Claude vede lo stesso messaggio e di solito riprova da solo. Un errore temporaneo non è legato all'idoneità alla modalità auto; non devi modificare le impostazioni
• Se i nuovi tentativi continuano a non riuscire, prosegui con attività di sola lettura e torna più tardi all'azione bloccata
• Su Amazon Bedrock, se il messaggio si ripresenta a ogni nuovo tentativo, verifica che il tuo account possa invocare il modello indicato: per i modelli Amazon Bedrock standard, conferma che la tua policy IAM ne consenta l'invocazione; per gli ID modello Mantle, contatta il team del tuo account AWS

Quando una richiesta al classificatore non riesce perché il tuo token OAuth è scaduto o è stato ruotato da un'altra sessione, Claude Code aggiorna il token e riprova la richiesta una volta, quindi una normale scadenza del token non si manifesta con questo messaggio. Prima della v2.1.216, un token scaduto o ruotato faceva fallire ogni richiesta al classificatore e la modalità auto negava ogni azione controllata con questo messaggio finché il token non veniva aggiornato.

Quando il classificatore ha restituito una risposta non analizzabile:

Auto mode could not evaluate this action and is blocking it for safety — run with --debug for details

Cosa fare:

• Riprova l'azione; di solito riesce al tentativo successivo
• Esegui claude --debug e ripeti l'azione per vedere i dettagli nel log di debug

Quando un controllo di sicurezza dell'API separato ha bloccato la richiesta al classificatore a causa di contenuti precedenti della conversazione:

Auto mode could not evaluate this action and is blocking it for safety — a safety check separate from auto mode blocked this request because of earlier conversation content — it isn't about the action itself — run with --debug for details

Claude Code nega l'azione ma comunica a Claude che non si tratta di un giudizio sulla pericolosità dell'azione e che deve proseguire con altre attività invece di riprovare. Questi rifiuti non vengono conteggiati nelle soglie di pausa della modalità auto. In un'esecuzione -p non interattiva, Claude Code non interrompe l'esecuzione. Ciò che Claude riceve dipende da dove ha richiesto l'azione:

• A un subagent in background in un'esecuzione -p senza --input-format stream-json, Claude Code restituisce un risultato di errore contenente Agent aborted: auto mode classifier request refused by the safety safeguard in headless mode
• In tutti gli altri casi, incluse le sessioni interattive e la conversazione principale di un'esecuzione -p, Claude Code restituisce quel rifiuto a Claude

Prima della v2.1.225, Claude Code conteggiava questi rifiuti nelle soglie di pausa e restituiva lo stesso messaggio di rifiuto di un vero blocco del classificatore.

Cosa fare:

• Non si tratta di una decisione sulla tua azione. Contenuti già presenti nella tua conversazione hanno attivato un filtro di sicurezza dell'API quando la modalità auto ha inviato la conversazione al classificatore
• Riprovare non servirà; gli stessi contenuti della conversazione attiveranno di nuovo il filtro
• In una sessione interattiva, passa a una modalità di permesso diversa in modo da poter approvare l'azione quando ti viene chiesto
• Avvia una nuova conversazione senza i contenuti che attivano il filtro

Quando la conversazione è diventata più grande della finestra di contesto del classificatore:

Auto mode classifier transcript exceeded context window — falling back to manual approval (try /compact to reduce conversation size)

Ciò che accade all'azione dipende da dove Claude l'ha richiesta:

• In una sessione interattiva, la modalità auto ripiega su una normale richiesta di permesso per quell'azione, così puoi approvarla o negarla manualmente
• A un subagent in background in un'esecuzione -p non interattiva senza --input-format stream-json, Claude Code restituisce un risultato di errore contenente Agent aborted: auto mode classifier transcript exceeded context window in headless mode e l'esecuzione continua
• Altrove in un'esecuzione -p senza un --permission-prompt-tool, non c'è alcuna richiesta di permesso su cui ripiegare, quindi l'azione non viene eseguita e l'esecuzione continua

Cosa fare:

• In una sessione interattiva, approva o nega l'azione nella richiesta che appare
• In una sessione interattiva, esegui /compact per ridurre le dimensioni della conversazione in modo che le azioni successive rientrino di nuovo nella finestra del classificatore

The server returned no safety verdict

Con la revisione del classificatore lato server, la modalità auto nega un'azione quando il server non fornisce un verdetto su di essa. Il rifiuto indica una categoria tra parentesi quando Claude Code riesce a determinarla, come (timed out):

The server-side auto mode classifier gave no verdict (timed out), so auto mode cannot determine the safety of <tool>.

Il resto del messaggio indica a Claude se un nuovo tentativo può essere utile. Prima di alcuni di questi rifiuti, Claude Code attende, in modo che il tentativo successivo di Claude non segua immediatamente. Durante l'attesa in una sessione interattiva, lo spinner mostra Auto mode check unavailable con un conto alla rovescia, e premendo Esc interrompi il turno.

Dopo dieci risposte consecutive senza verdetto, la modalità auto interrompe il turno:

Auto mode is unavailable — the server returned no safety verdict for the last 10 responses, so Claude stopped. Send a message to try again, or switch out of auto mode.

Il messaggio di interruzione appare in un punto diverso a seconda del tipo di sessione:

• In una sessione interattiva, il messaggio appare come avviso nella trascrizione e il turno termina
• In un'esecuzione -p non interattiva, l'esecuzione termina e segnala un errore di esecuzione. Con l'output di testo predefinito, il messaggio viene stampato su stderr.
• Quando un subagent ha raggiunto il limite, il subagent si ferma prima di terminare e Claude riceve ciò che ha prodotto, con una nota che indica che la modalità auto lo ha fermato

Cosa fare:

• Invia un altro messaggio per far riprovare Claude. Il conteggio delle risposte riparte da zero.
• Se l'interruzione si ripete e le tue richieste passano attraverso un gateway o proxy LLM, verifica se tronca o riscrive le risposte in streaming. La sezione Revisione del classificatore lato server indica quale comportamento del gateway causa i rifiuti, e la guida alla compatibilità dei gateway elenca cosa deve essere inoltrato senza modifiche.
• Imposta CLAUDE_CODE_AUTO_MODE_SERVER=0 prima di avviare Claude Code per usare invece le sue richieste al classificatore. Prima della v2.1.281, Claude Code non leggeva la variabile su una connessione diretta ad Anthropic API.
• Per approvare tu stesso le azioni, esci dalla modalità auto

Prima della v2.1.280, Claude Code negava immediatamente ogni azione proveniente da una risposta senza verdetto e non interrompeva mai il turno.

Agent terminated early due to an API error

Una richiesta API di un subagent non è riuscita in modo definitivo, ad esempio perché è stato raggiunto un limite di utilizzo o perché i nuovi tentativi per un errore del server si sono esauriti, quindi il subagent si è fermato prima di completare la sua attività. Questo messaggio richiede Claude Code v2.1.199 o successivo; prima di allora il testo dell'errore API veniva restituito a Claude come se fosse il risultato del subagent.

Agent terminated early due to an API error: <error detail>

Cosa fare:

• Individua la sezione di questa pagina corrispondente al dettaglio dell'errore dopo i due punti, come Limiti di utilizzo o Errori del server, e segui i passaggi di quella sezione
• Una volta risolto l'errore sottostante, chiedi a Claude di riprovare l'attività o di riprendere il subagent

Quando un rate limit, un sovraccarico o un errore del server interrompe un subagent in primo piano che ha già prodotto output di testo, Claude riceve quell'output parziale contrassegnato come incompleto invece di questo errore. Anche un subagent il cui unico output erano chiamate agli strumenti riceve questo errore; nella v2.1.199 quel caso restituiva invece un risultato parziale vuoto. Consulta Errori API nei subagent.

Limiti di utilizzo

La maggior parte degli errori in questa sezione significa che è stata raggiunta una quota associata al tuo account o al tuo piano. Tre funzionano diversamente: Server is temporarily limiting requests è una limitazione lato server non correlata alla quota del tuo piano, Usage credits required for 1M context è un controllo di diritto piuttosto che una quota esaurita, e The prompt to confirm went unanswered significa che un prompt di consenso per i crediti di utilizzo è stato chiuso senza risposta, indipendentemente dal fatto che sia stata raggiunta una quota.

You've hit your session limit

I piani di abbonamento includono un'indennità di utilizzo mobile. Quando si esaurisce, vedrai uno di questi messaggi:

You've hit your session limit · resets 3:45pm
You've hit your weekly limit · resets Mon 12:00am
You've hit your Opus limit · resets 3:45pm
You've hit your Sonnet limit · resets 3:45pm

Claude Code blocca ulteriori richieste fino all'ora di ripristino mostrata nel messaggio. I limiti di sessione e settimanali sono condivisi tra tutti i modelli, quindi il cambio di modelli non ripristina l'accesso. I limiti Opus e Sonnet si applicano ciascuno solo alle richieste a quella famiglia di modelli, quindi il passaggio a un modello al di fuori della famiglia con /model ti mantiene al lavoro.

In una sessione interattiva con accesso tramite abbonamento claude.ai, Claude Code può anche attendere nella sessione aperta e continuare l'attività interrotta poco dopo il ripristino. Vedi Wait for a usage limit to reset per quello che vedi, come avviare o annullare un'attesa e come disattivare la continuazione automatica. Prima della v2.1.234, Claude Code non offriva questa attesa.

L'utilizzo conta sia per le indennità di sessione che settimanali contemporaneamente. Un singolo picco di attività intensa, come un grande fanout di flusso di lavoro, può esaurire l'indennità settimanale prima che la finestra di sessione si ripristini.

Cosa fare:

• Attendi l'ora di ripristino mostrata nell'errore
• Nella scheda Code dell'app Desktop, la scheda session-limit offre una casella di controllo Auto-continue when limits reset. La scheda weekly-limit non lo fa. Quando è selezionata, l'app Desktop ritenta il turno interrotto dopo il ripristino e mostra l'ora del nuovo tentativo sulla scheda. La casella di controllo Desktop e l'impostazione Continue automatically at usage limit della CLI in /config sono separate, quindi disattiva ciascuna per conto proprio.
• Per il limite Opus o Sonnet, esegui /model e passa a un modello al di fuori di quella famiglia per continuare a lavorare. Ogni modello ha la propria cache di prompt, quindi la richiesta successiva rilegge l'intera conversazione senza hit della cache; vedi Switching models
• Esegui /usage per vedere i limiti del tuo piano e quando si ripristinano
• Esegui /usage-credits per acquistare utilizzo aggiuntivo su Pro e Max, o per richiederlo al tuo amministratore su Team ed Enterprise. Vedi usage credits for paid plans per come viene fatturato.
• Per aggiornare il tuo piano per limiti di base più elevati, vedi claude.com/pricing

Prima che una finestra si esaurisca, Claude Code può avvertirti che hai utilizzato la maggior parte di essa, con un messaggio come You've used 85% of your session limit · resets 3:45pm. Per monitorare l'indennità rimanente continuamente, aggiungi i campi rate_limits a una riga di stato personalizzata, oppure nell'app Desktop fai clic sull'anello di utilizzo accanto al selettore di modelli.

Usage credits required for 1M context

Il modello selezionato utilizza la finestra di contesto estesa da 1M token e il tuo piano lo include solo tramite crediti di utilizzo.

API Error: Usage credits required for 1M context · run /usage-credits to turn them on (they take effect after you restart Claude Code), or /model to switch to standard context

In una sessione che l'app Claude Desktop esegue, il suggerimento non nomina alcun comando: punta alla pagina delle impostazioni di utilizzo di claude.ai, oppure sui piani Team ed Enterprise dice di attivare i crediti di utilizzo su claude.ai/admin-settings/usage o di chiedere al tuo amministratore.

Questo è un controllo di diritto, non un esaurimento della quota. Si attiva anche quando le tue indennità di sessione e settimanali hanno capacità rimanente. Vedi Extended context per quali piani includono il contesto 1M direttamente e quali richiedono crediti di utilizzo.

Quando questo errore appare a metà conversazione perché il contesto è cresciuto oltre 200K token, Claude Code compatta automaticamente la conversazione al di sotto del limite di contesto standard e mantiene la sessione a quel limite in seguito, quindi non è necessaria alcuna azione. Nelle versioni precedenti alla v2.1.172, l'errore si ripeteva su ogni richiesta successiva incluso /compact; esegui /clear su quelle versioni per recuperare. I passaggi seguenti si applicano quando hai esplicitamente selezionato un modello [1m].

Cosa fare:

• Esegui /model e seleziona la variante senza il suffisso [1m] per tornare alla finestra di contesto standard
• Dove il messaggio nomina /usage-credits, eseguilo per attivare la fatturazione a consumo per la variante 1M su Pro e Max, o per richiedere crediti di utilizzo al tuo amministratore su Team ed Enterprise. Una volta che i crediti di utilizzo sono attivati, riavvia Claude Code o avvia una nuova sessione, a seconda di quello che dice il messaggio. Fino al riavvio, la sessione rimane al limite di contesto standard.
• Se l'errore persiste dopo /model, un ID modello 1M potrebbe essere impostato altrove. Vedi Setting your model per i percorsi di configurazione da controllare in ordine di priorità.
• Per rimuovere completamente le varianti 1M dal selettore di modelli, imposta CLAUDE_CODE_DISABLE_1M_CONTEXT=1

Prima della v2.1.268, il messaggio terminava con run /usage-credits to turn them on, or /model to switch to standard context e non menzionava il riavvio.

The prompt to confirm went unanswered

Se il tuo account richiede il consenso per i crediti di utilizzo Fable, Claude Code ti chiede di confermare prima che una richiesta Fable fatturi i crediti di utilizzo. Quando il prompt di consenso si chiude senza che nessuno lo risponda, Claude Code termina il turno con uno di questi messaggi:

Fable limit reached · continuing on Fable 5.1 uses usage credits, and the prompt to confirm went unanswered — nothing was sent · answer it where this session is running, or /model to change
Fable 5.1 now uses usage credits · the prompt to confirm went unanswered — nothing was sent · answer it where this session is running, or /model to change

I messaggi nominano il modello Fable della sessione, quindi su Fable 5 leggono continuing on Fable 5 e Fable 5 now uses usage credits. Prima della v2.1.257, il primo messaggio iniziava Fable 5 limit reached.

Questo accade nelle sessioni Remote Control, sessioni in background, team agente sessioni compagni, e sessioni che un'altra applicazione ospita tramite Agent SDK. Per quando Claude Code chiude il prompt, vedi Fable and usage credits.

Cosa fare:

• Dove viene eseguita la sessione, al terminale o nell'applicazione che la ospita, invia un altro prompt e rispondi al prompt di consenso quando riappare. Per una sessione in background, collegati prima dalla vista agenti. Reinviare da un client Remote Control mostra di nuovo questo messaggio, perché il client non può visualizzare il prompt.
• Esegui /model per passare a un modello che non fattura i crediti di utilizzo
• Per darti più tempo, imposta dialogExpiry su un valore più lungo o "never"

Prima della v2.1.236, questo messaggio non appariva: mentre un client Remote Control era connesso, Claude Code attendeva 60 secondi per una risposta e poi continuava il turno sul tuo modello predefinito.

Server is temporarily limiting requests

L'API ha applicato una limitazione di breve durata non correlata alla quota del tuo piano.

API Error: Server is temporarily limiting requests (not your usage limit)

Claude Code distingue questi dalla tua quota di piano per l'assenza delle intestazioni di quota unificata che una vera risposta di limite porta. A partire dalla v2.1.199 questo viene ritentato automaticamente con backoff prima di essere mostrato, indipendentemente da come ti autentichi. Nelle versioni precedenti, una sessione con accesso tramite abbonamento claude.ai ha fallito il turno alla prima occorrenza; solo le chiavi API e gli accessi Enterprise lo hanno ritentato.

Cosa fare:

• Attendi brevemente e riprova
• Controlla status.claude.com se persiste

Request rejected (429)

Hai raggiunto il limite di velocità configurato per la tua chiave API, il progetto Amazon Bedrock o il progetto Google Cloud.

API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com.

La frase finale nomina dove controllare l'integrità del servizio e varia in base al provider. Le configurazioni Amazon Bedrock, Google Cloud's Agent Platform e Microsoft Foundry nominano lo stato del servizio di quel provider invece della pagina di stato Anthropic. Un ANTHROPIC_BASE_URL personalizzato nomina l'host del gateway.

Quando un proxy, un load balancer o un gateway tra Claude Code e l'API risponde con la propria pagina HTML 429, il testo dopo il · è il titolo di quella pagina quando ne ha uno, come Too Many Requests. Prima della v2.1.281, l'intero markup della pagina era stampato dopo il ·.

Cosa fare:

• Esegui /status e conferma che la credenziale attiva è quella che ti aspetti. Un ANTHROPIC_API_KEY casuale nel tuo ambiente può instradare le richieste attraverso una chiave di livello inferiore invece del tuo abbonamento.
• Controlla la console del tuo provider per i limiti attivi e richiedi un livello più elevato se necessario
• Per le chiavi API Anthropic, vedi il riferimento ai limiti di velocità per come funzionano i livelli e come impostare i limiti di spesa per workspace
• Riduci la concorrenza: abbassa CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY, evita di eseguire molti subagenzi paralleli, o passa a un modello più piccolo con /model per esecuzioni script ad alto volume

You've hit your monthly spend limit

L'utilizzo incluso nel tuo piano non può coprire questa richiesta, e i crediti di utilizzo che altrimenti la pagherebbero hanno raggiunto un limite di spesa. Ciò accade quando una delle finestre di utilizzo del tuo piano si è esaurita, o quando la richiesta è una che solo i crediti di utilizzo pagano, come una richiesta a un modello che fattura ai crediti di utilizzo. Il messaggio nomina il limite che ti ha bloccato. Il testo dopo il · dice come aumentare quel limite, e varia in base al tuo piano e se gestisci la fatturazione:

You've hit your monthly spend limit · raise it at claude.ai/settings/usage
You've hit your individual spend limit · ask your admin for a higher limit
You've hit your org's monthly spend limit · visit claude.ai/admin-settings/usage to raise it
You've hit your team's shared budget · ask your admin to raise it at claude.ai/admin-settings/usage
You've hit your channel's monthly spend limit · an org owner or channel manager can raise it in the channel's Claude settings

team's shared budget è un budget in pool che un amministratore ha assegnato a un gruppo a cui appartieni; il messaggio non nomina il gruppo. channel's monthly spend limit è il budget del canale Slack in cui viene eseguita la sessione, quindi la tua organizzazione potrebbe ancora avere budget al di fuori di esso.

Quando una delle finestre del tuo piano è quella che si è esaurita, il messaggio dice anche quando quella finestra si ripristina, ad esempio · your session limit resets 3:45pm, e l'accesso ritorna allora senza che nessuno aumenti il limite. Nelle organizzazioni con fatturazione basata sull'utilizzo, il messaggio dice usage limit al posto di spend limit, come in You've hit your individual usage limit.

Prima della v2.1.239, il messaggio non nominava l'ora di ripristino della finestra del piano. Prima della v2.1.268, il budget in pool di un gruppo produceva il messaggio individual spend limit invece di team's shared budget.

Se ti connetti tramite un gateway di app Claude e vedi spend limit reached minuscolo, quello è il limite dell'operatore del gateway invece; vedi Spend limit reached.

Cosa fare:

• Su Pro e Max, aumenta il tuo limite di spesa mensile in Settings > Usage su claude.ai, o esegui /usage-credits
• Su Team ed Enterprise, aumenta il limite in Admin settings > Usage se gestisci la fatturazione, o chiedi a un amministratore di farlo. /usage-credits invia quella richiesta al tuo amministratore per te
• Per il limite di un canale, chiedi a un proprietario dell'organizzazione o al manager del canale di aumentarlo su claude.ai. Vedi Per-channel limits nella documentazione Claude Tag
• Se il messaggio nomina un'ora di ripristino per la finestra del tuo piano, puoi aspettare invece
• Esegui /usage per vedere le finestre del tuo piano e quando ciascuna si ripristina

Spend limit reached

Ti connetti tramite un gateway di app Claude e hai superato un limite di spesa impostato dall'operatore del gateway. Il gateway blocca le tue richieste fino a quando il periodo denominato non si ripristina o l'operatore non aumenta il limite. Contrassegna ogni risposta 429 bloccata con x-should-retry: false, quindi Claude Code mostra questo messaggio senza ritentare.

spend limit reached (daily; resets 2026-08-09 00:00 UTC)

Il messaggio nomina il periodo del limite e l'ora di ripristino, e quando l'operatore ha configurato un blocked_message, le sue istruzioni lo seguono. Prima della v2.1.225, il messaggio leggeva solo spend limit reached; un gateway su una versione precedente invia ancora quella forma più breve.

Cosa fare:

• Attendi l'ora di ripristino che il messaggio nomina, o segui le istruzioni dell'operatore se il messaggio le contiene
• Chiedi al tuo operatore del gateway di aumentare il limite se lo raggiungi regolarmente

Un messaggio correlato, spend limit unavailable, significa che il gateway non poteva leggere i suoi record di spesa e ha bloccato la richiesta come precauzione piuttosto che per il tuo limite. Di solito si risolve da solo; se persiste, comunica al tuo operatore del gateway.

Credit balance is too low

L'organizzazione della tua Console ha esaurito i crediti prepagati, o Claude Code sta inviando le tue richieste con una chiave API Console quando intendevi usare il tuo abbonamento.

Credit balance is too low

Cosa fare:

• Se hai un piano Pro, Max, Team o Enterprise e vedi questo, esegui /status e controlla la riga API key. Un ANTHROPIC_API_KEY approvato nel tuo ambiente instrada le richieste attraverso quella chiave invece del tuo abbonamento. Annullalo nella shell corrente e rimuovilo dal tuo profilo shell, quindi riavvia claude. Esegui /login se non hai ancora effettuato l'accesso con il tuo abbonamento.
• Aggiungi crediti su platform.claude.com/settings/billing, e considera di abilitare il ricaricamento automatico lì in modo che il saldo si riempia prima di raggiungere lo zero
• Imposta i limiti di spesa per workspace nella Console per evitare che un singolo progetto dreni il saldo dell'organizzazione. Vedi Manage costs effectively.

Could not update your spend limit

Il server ha rifiutato una modifica del limite di spesa che hai effettuato dal prompt che appare quando raggiungi il tuo limite di spesa.

Could not update your spend limit: <reason from the server>

Quando il server spiega il rifiuto, il messaggio termina con quel motivo, e ritentare lo stesso valore fallisce di nuovo. Quando il fallimento non ha un motivo fornito dal server, come una connessione interrotta, il messaggio legge Could not update your spend limit. Press Enter to retry. e ritentare può avere successo. Prima della v2.1.216, Claude Code mostrava la forma generica per ogni fallimento.

Cosa fare:

• Se il messaggio include un motivo, scegli un limite che lo soddisfi, come un importo inferiore
• Se il messaggio mostra solo la forma generica, ritenta; il fallimento potrebbe essere transitorio
• Se la modifica continua a fallire, effettuala dalle tue impostazioni di fatturazione claude.ai nel browser invece

Errori di autenticazione

Questi errori indicano che Claude Code non riesce a dimostrare la tua identità all'API. Esegui /status in qualsiasi momento per vedere quale credenziale è attualmente attiva.

Accesso non effettuato

Nessuna credenziale valida è disponibile per questa sessione.

Not logged in · Please run /login

In una sessione eseguita dall'app Claude Desktop, come la scheda Code o Cowork, il messaggio è Authentication required · Sign in again to continue e devi accedere di nuovo dall'app.

Se accedi con il tuo account claude.ai in un'altra finestra di Claude Code che usa la stessa directory di configurazione, una sessione interattiva che mostra questo messaggio inizia a usare quell'accesso da sola. Non devi riavviarla.

Prima della v2.1.286 su macOS, la sessione poteva continuare a mostrare il messaggio dopo che avevi effettuato l'accesso da un'altra finestra. In quelle versioni, riavvia la sessione che mostra il messaggio.

Cosa fare:

• Esegui /login per autenticarti con il tuo abbonamento Claude o il tuo account Console
• Se ti aspettavi che una variabile d'ambiente ti autenticasse, verifica che ANTHROPIC_API_KEY sia impostata ed esportata nella shell in cui hai avviato claude
• Per CI o automazioni in cui l'accesso interattivo non è possibile, configura uno script apiKeyHelper che recuperi una chiave all'avvio
• Consulta Precedenza dell'autenticazione per capire quale credenziale usa Claude Code quando ne sono presenti diverse

Se ti viene chiesto ripetutamente di accedere, consulta Accesso non effettuato o token scaduto per i controlli dell'orologio di sistema e i passaggi di ripristino dell'archiviazione delle credenziali su macOS.

Impossibile determinare il metodo di autenticazione

La sessione ha raggiunto il client API senza alcuna credenziale. Le sessioni in background e le sessioni cloud mostrano questo messaggio quando il worker si avvia senza una credenziale. Le esecuzioni interattive, con -p e con l'Agent SDK segnalano la stessa condizione come Accesso non effettuato e scrivono questa stringa solo nel proprio log di debug, quindi se l'hai trovata lì, segui quella voce.

Could not resolve authentication method. Expected one of apiKey, authToken, credentials, config, or profile to be set. Or for one of the "X-Api-Key" or "Authorization" headers to be explicitly omitted

Nelle versioni attuali l'errore indica che nessuna credenziale era disponibile per il processo worker. Prima della v2.1.174, una sessione in background assegnata a un worker inattivo pre-inizializzato poteva fallire in questo modo anche quando erano configurate credenziali valide. Prima della v2.1.176, poteva succedere anche a una sessione cloud rimasta inattiva prima di essere presa in carico. Aggiorna per risolvere.

Cosa fare:

• Aggiorna alla v2.1.176 o successiva se questo messaggio compare in una sessione in background o cloud e le tue credenziali sono già configurate
• Verifica che ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN o le credenziali del tuo provider cloud siano impostate nell'ambiente che avvia il worker, non solo nella tua shell interattiva
• Per l'Agent SDK, consulta la configurazione dell'autenticazione nella guida rapida
• Esegui /status in una sessione interattiva nello stesso ambiente per verificare quale origine delle credenziali viene risolta

Chiave API non valida

La variabile d'ambiente ANTHROPIC_API_KEY o lo script apiKeyHelper ha restituito una chiave che l'API ha rifiutato, oppure Claude Code ha bloccato una chiave proveniente da ANTHROPIC_API_KEY prima di inviarla.

Invalid API key · Fix external API key

Quando il messaggio prosegue dopo Fix external API key con una descrizione come Invalid X-Api-Key header value from ANTHROPIC_API_KEY: it contains a line break at character 41 (120 characters on 2 lines)., l'API non ha mai visto la chiave. Claude Code ha trovato un carattere che le intestazioni HTTP non possono contenere e ha interrotto la richiesta prima di inviarla. Consulta Valore dell'intestazione della richiesta non valido per sapere come leggere la descrizione e correggere il valore.

Cosa fare:

• Controlla eventuali errori di battitura e verifica che la chiave non sia stata revocata nella Console
• Nella stessa shell, esegui env | grep ANTHROPIC, oppure in PowerShell Get-ChildItem Env:ANTHROPIC*. Strumenti come direnv, i plugin di shell per dotenv e i terminali degli IDE possono caricare una chiave obsoleta da un file .env nel tuo progetto senza che tu la imposti esplicitamente.
• Rimuovi ANTHROPIC_API_KEY ed esegui /login per usare invece l'autenticazione tramite abbonamento
• Se la chiave proviene da uno script apiKeyHelper, esegui lo script direttamente per verificare che stampi una chiave valida su stdout
• Esegui /status per verificare quale origine delle credenziali sta effettivamente usando Claude Code

Il tuo script apiKeyHelper non funziona

Claude Code ha eseguito il comando nella tua impostazione apiKeyHelper e non ha ricevuto una chiave. Senza una chiave, la richiesta raggiunge l'API con una credenziale segnaposto e l'API la rifiuta con 401. Il pannello Authentication nel terminale mostra quale di questi casi si è verificato:

• Il comando è terminato con un errore o è andato in timeout
• Il comando non ha stampato nulla su stdout
• Il comando ha stampato qualcosa oltre alla chiave, come un banner di accesso o una riga di log. Il pannello mostra returned output that cannot be used as an API key e indica cosa non va, senza ripetere l'output. Prima della v2.1.227, Claude Code inviava qualunque cosa il comando stampasse, dopo aver rimosso gli spazi iniziali e finali.

Your apiKeyHelper script is failing · This usually means you need to re-authenticate with your provider · Run /status to see the script's error output

In modalità non interattiva, anche stderr riporta il motivo specifico, preceduto da apiKeyHelper failed:.

Claude Code riesegue lo script e riprova la richiesta fino ad altre due volte prima di mostrare questo messaggio, quindi l'errore emerge entro tre tentativi. Prima della v2.1.208, Claude Code esauriva l'intero budget di nuovi tentativi reinviando la richiesta con la credenziale segnaposto e poi segnalava un generico errore di autenticazione 401 invece dell'errore dello script.

Eseguire /login non aiuta in questo caso: l'output dell'helper ha la precedenza su un accesso salvato finché l'impostazione è presente.

Cosa fare:

• Esegui direttamente nella tua shell il comando configurato in apiKeyHelper per riprodurre l'errore
• Se il comando segnala una sessione scaduta, autenticati di nuovo con il tuo provider di credenziali, ad esempio accedendo di nuovo al tuo SSO o al tuo vault dei segreti
• Correggi il comando in modo che stampi su stdout solo la chiave, come singolo token di caratteri ASCII stampabili lungo al massimo 16.384 caratteri, e termini con codice di uscita 0. Consulta ruotare le credenziali con apiKeyHelper per una configurazione funzionante.
• Esegui /status per vedere l'errore e verificare che apiKeyHelper sia l'origine delle credenziali attiva. La riga apiKeyHelper mostra Failing con i dettagli dell'ultimo errore, come il codice di uscita e l'output di errore del comando, e scompare dopo la successiva esecuzione riuscita. Prima della v2.1.274, /status mostrava solo l'origine delle credenziali, non l'errore.
• Ogni volta che il comando fallisce, il suo codice di uscita e il suo output di errore compaiono anche in un pannello Authentication nel terminale. Prima della v2.1.212, il pannello si intitolava Cloud authentication.

Valore dell'intestazione della richiesta non valido

Un valore che Claude Code stava per inviare come intestazione di una richiesta contiene un carattere che le intestazioni HTTP non possono contenere: un'interruzione di riga, un byte NUL o un carattere oltre U+00FF, come una virgoletta curva o uno spazio a larghezza zero. Claude Code interrompe la richiesta prima di inviare qualsiasi cosa e indica la variabile o l'impostazione da correggere. La causa abituale è una credenziale incollata da un documento o da una chat che conteneva un carattere invisibile o un'interruzione di riga accidentale.

Claude Code esegue questo controllo quando invia richieste all'API Claude direttamente o tramite un gateway LLM. Con un provider cloud di terze parti come Amazon Bedrock, Claude Code non lo esegue prima dell'invio.

Invalid auth token · Fix external auth token
Invalid ANTHROPIC_CUSTOM_HEADERS · Fix the environment variable
Invalid request header from the environment · Fix the environment variable

La prima parte del messaggio dipende dall'origine del valore errato:

• Invalid auth token: un bearer token da ANTHROPIC_AUTH_TOKEN o CLAUDE_CODE_OAUTH_TOKEN
• Invalid ANTHROPIC_CUSTOM_HEADERS: un nome o un valore di intestazione che hai impostato in ANTHROPIC_CUSTOM_HEADERS. La descrizione indica quale coppia Name: Value è responsabile, ad esempio distinct header 2 of 3 parsed from ANTHROPIC_CUSTOM_HEADERS, senza ripetere il nome o il valore, dato che li hai scelti tu.
• Invalid request header from the environment: un valore che Claude Code copia in un'intestazione della richiesta da un'altra variabile d'ambiente, come CLAUDE_AGENT_SDK_CLIENT_APP. La descrizione indica la variabile da correggere.

Claude Code segnala una ANTHROPIC_API_KEY errata intercettata da questo controllo come Chiave API non valida, con la stessa descrizione finale. Segnala invece una credenziale /login salvata errata come Accesso non effettuato; esegui /login per salvarne una nuova. L'output di uno script apiKeyHelper non arriva mai a questo controllo: Claude Code lo convalida quando lo script viene eseguito, e un output che un'intestazione HTTP non può contenere fallisce con Il tuo script apiKeyHelper non funziona.

Dopo il secondo ·, il messaggio descrive il problema, come in questo esempio completo:

Invalid auth token · Fix external auth token · Invalid Authorization header value from ANTHROPIC_AUTH_TOKEN: it contains a line break at character 41 (120 characters on 2 lines).

Le posizioni contano i caratteri a partire da uno. La descrizione è costruita con frasi fisse e conteggi di caratteri, quindi non include mai il valore stesso. Indica il carattere problematico solo quando si tratta di un carattere invisibile o tipografico noto, come un byte-order mark, uno spazio a larghezza zero o una virgoletta curva, e segnala qualsiasi altro carattere come a non-ASCII character.

Cosa fare:

• Reimposta la variabile o l'impostazione indicata dal messaggio, digitando di nuovo i caratteri intorno alla posizione segnalata anziché incollarli di nuovo dalla stessa fonte
• Per ANTHROPIC_CUSTOM_HEADERS, mantieni una coppia Name: Value per riga e riscrivi la coppia indicata dal messaggio
• Esegui /status per verificare quale origine delle credenziali è attiva

Questa organizzazione è stata disabilitata

Claude Code sta usando una ANTHROPIC_API_KEY obsoleta di un'organizzazione Console disabilitata. Quando hai un accesso tramite abbonamento salvato, la chiave ha la precedenza su di esso.

Your ANTHROPIC_API_KEY belongs to a disabled organization · Unset the environment variable to use your subscription instead
Your ANTHROPIC_API_KEY belongs to a disabled organization · Update or unset the environment variable
API Error: 400 ... This organization has been disabled.

Il suggerimento dopo il · dipende dalle tue credenziali salvate: la prima forma compare quando un /login salvato può subentrare dopo che rimuovi la chiave, la seconda quando la chiave è la tua unica credenziale.

Le variabili d'ambiente hanno la precedenza su /login, quindi una chiave esportata nel profilo della tua shell o caricata da un file .env viene usata anche quando hai un abbonamento Pro o Max funzionante. In modalità non interattiva (-p), la chiave viene sempre usata quando è presente.

Cosa fare:

• Rimuovi ANTHROPIC_API_KEY nella shell corrente e dal profilo della tua shell, poi riavvia claude
• Se il messaggio dice Update or unset, non hai un accesso salvato a cui ripiegare. Rimuovi la chiave ed esegui /login, oppure sostituisci la chiave con una di un'organizzazione Console attiva.
• Esegui /status in seguito per verificare che la credenziale attiva sia il tuo abbonamento
• Se nessuna variabile d'ambiente è impostata e l'errore persiste, contatta l'assistenza o accedi con un account diverso.

La tua organizzazione ha disabilitato l'autenticazione con chiave API

Questo messaggio richiede Claude Code v2.1.169 o successiva. L'amministratore della tua organizzazione Console ha disattivato l'autenticazione con chiave API, quindi l'API rifiuta la chiave che Claude Code sta inviando. Il suggerimento di ripristino dopo il · varia in base all'origine della chiave:

Your organization has disabled API key authentication · Run /login to sign in with your claude.ai account
Your organization has disabled API key authentication · Unset ANTHROPIC_API_KEY to use your claude.ai account instead
Your organization has disabled API key authentication · Unset ANTHROPIC_API_KEY and run /login to sign in with your claude.ai account
Your organization has disabled API key authentication · Unset the apiKeyHelper setting and run /login to sign in with your claude.ai account
Your organization has disabled API key authentication · Sign in again with your claude.ai account

L'ultima forma compare in una sessione eseguita dall'app Claude Desktop, come la scheda Code o Cowork, dove accedi di nuovo dall'app.

Le variabili d'ambiente e apiKeyHelper hanno la precedenza su /login, quindi eseguire solo /login non aiuta finché uno dei due fornisce ancora una chiave. Consulta Precedenza dell'autenticazione.

Cosa fare:

• Se il messaggio indica ANTHROPIC_API_KEY, rimuovila nella shell corrente e dal profilo della tua shell o dal file .env, poi riavvia claude
• Se il messaggio indica apiKeyHelper, rimuovi l'impostazione apiKeyHelper dal tuo settings.json
• Esegui /login per accedere con il tuo account claude.ai
• Esegui /status in seguito per verificare che la credenziale attiva sia il tuo abbonamento e non una chiave API
• Se hai bisogno dell'autenticazione con chiave API per le automazioni, chiedi all'amministratore della tua organizzazione di riattivarla nella Console

La tua organizzazione ha disabilitato l'accesso tramite abbonamento Claude

La tua organizzazione Claude non consente di accedere a Claude Code con un accesso tramite abbonamento. Eseguire di nuovo /login con lo stesso account restituisce lo stesso errore.

Your organization has disabled Claude subscription access for Claude Code · Use an Anthropic API key instead, or ask your admin to enable access

Si tratta di un'impostazione dell'organizzazione lato server, quindi non può essere sovrascritta da impostazioni locali, variabili d'ambiente o flag della CLI.

L'Agent SDK e la modalità non interattiva -p lo riportano come codice di errore oauth_org_not_allowed.

Cosa fare:

• Chiedi al tuo amministratore di abilitare l'accesso a Claude Code per la tua organizzazione
• Autenticati con una chiave API della Console invece che con il tuo abbonamento. Consulta Autenticazione con Claude Console per la configurazione.
• Se sei l'amministratore e non vedi un'opzione per abilitare l'accesso, contatta l'assistenza Anthropic

Le routine sono disabilitate dal criterio della tua organizzazione

Un Owner della tua organizzazione Team o Enterprise ha disattivato le routine a livello di organizzazione. L'errore compare quando provi a creare o eseguire una routine, ad esempio dall'interfaccia Routine su claude.ai/code. Su Claude Code v2.1.227 o successiva, la stessa impostazione nasconde anche /schedule nella CLI.

Routines are disabled by your organization's policy.

Si tratta di un'impostazione lato server, quindi non può essere sovrascritta da impostazioni locali, variabili d'ambiente o flag della CLI.

Cosa fare:

• Chiedi a un Owner della tua organizzazione di attivare l'interruttore Routine su claude.ai/admin-settings/claude-code
• Per lavori pianificati una tantum che non richiedono routine a livello di organizzazione, consulta attività pianificate

Remote Control richiede l'API Anthropic

La sessione non comunica direttamente con l'API Anthropic, come richiesto da Remote Control.

Remote Control is only available when using Claude via api.anthropic.com. CLAUDE_CODE_USE_BEDROCK is set, so this session is using Amazon Bedrock — unset it (or run in a shell without it) to use Remote Control.

Una seconda frase spiega cosa ha instradato la sessione lontano dall'API Anthropic; prima della v2.1.219, il messaggio era composto solo dalla prima frase. A seconda della causa, il messaggio indica:

• Una variabile del provider CLAUDE_CODE_USE_*, come CLAUDE_CODE_USE_BEDROCK per Amazon Bedrock o CLAUDE_CODE_USE_VERTEX per Agent Platform di Google Cloud
• ANTHROPIC_BASE_URL che punta a un host diverso da api.anthropic.com, come un gateway LLM o un proxy, anche quando accedi con claude.ai; prima della v2.1.196, un URL di base personalizzato non bloccava Remote Control
• ANTHROPIC_UNIX_SOCKET impostata, per cui la sessione invia le sue richieste tramite un socket locale anziché a api.anthropic.com
• Un accesso tramite gateway cloud aziendale effettuato con /login, che non supporta Remote Control e non ha alcuna variabile da rimuovere

Cosa fare:

• Rimuovi la variabile indicata dal messaggio, come CLAUDE_CODE_USE_BEDROCK o ANTHROPIC_BASE_URL, e riavvia la sessione, oppure avvia Remote Control da una sessione che comunica direttamente con l'API Anthropic
• Se la variabile non è impostata nella tua shell, controlla la chiave env nei tuoi file di impostazioni, che applica variabili d'ambiente a ogni sessione
• Per questo e gli altri messaggi di avvio di Remote Control, consulta Risoluzione dei problemi di Remote Control

Remote Control non è riuscito ad aggiornare il tuo accesso

Claude Code mantiene attiva una connessione Remote Control usando credenziali di breve durata che ottiene e rinnova tramite il tuo accesso claude.ai salvato. Quando claude.ai smette di accettare quell'accesso, o Claude Code non ha più alcun accesso salvato, Claude Code interrompe Remote Control e ha bisogno che tu acceda di nuovo. Entrambi gli errori possono verificarsi mentre Claude Code si sta ancora connettendo oppure più tardi, quando rinnova le credenziali.

Quando Claude Code chiede al servizio di accesso di aggiornare il tuo accesso salvato e non riceve risposta, mantiene Remote Control in esecuzione e riprova l'aggiornamento finché la credenziale corrente della connessione è ancora valida. Un aggiornamento non riceve risposta quando Claude Code non riesce a raggiungere il servizio di accesso, la richiesta va in timeout o il servizio fallisce senza rifiutare il tuo accesso. Se il servizio di accesso non risponde ancora quando quella credenziale scade, Claude Code interrompe Remote Control e segnala OAuth token refresh failed.

Quando Claude Code interrompe Remote Control, mostra il motivo in un avviso e in una riga della trascrizione che inizia con Remote Control disconnected. La tua sessione locale continua a funzionare senza Remote Control. Questa sezione tratta queste righe:

Remote Control disconnected — Claude.ai login expired — run /login to restore Remote Control
Remote Control disconnected — Claude.ai login expired — run /login, then /remote-control
Remote Control disconnected — Claude.ai login was rejected — run /login, then /remote-control
Remote Control disconnected — OAuth token unavailable — run /login to restore Remote Control
Remote Control disconnected — OAuth token refresh failed — run /login to re-authenticate
Remote Control disconnected — JWT refresh failed: no OAuth token — run /login
Remote Control disconnected — Signed out of Claude — run /login, then /remote-control

Claude Code indica la causa nella parte centrale del messaggio:

• Claude.ai login expired e Claude.ai login was rejected: claude.ai non accetta più il tuo token di accesso salvato, perché è scaduto o è stato revocato
• OAuth token unavailable: Claude Code non aveva alcun token di accesso salvato quando la credenziale della connessione doveva essere rinnovata
• OAuth token refresh failed: claude.ai ha rifiutato il tuo token di accesso salvato mentre Claude Code si stava riconnettendo, e l'aggiornamento del token non ne ha prodotto uno nuovo
• JWT refresh failed: no OAuth token: Claude Code non ha trovato alcun token di accesso salvato con cui rinnovare
• Signed out of Claude: sei uscito su questa macchina, ad esempio eseguendo /logout in un altro terminale, quindi Claude Code non ha più alcun accesso salvato con cui rinnovare la connessione

Cosa fare:

• Esegui /login per accedere di nuovo
• Esegui /remote-control per riconnettere la sessione. I messaggi che terminano con run /login to restore Remote Control non richiedono questo passaggio: Claude Code si riconnette da solo una volta effettuato l'accesso.

Prima della v2.1.224, OAuth token refresh failed — run /login to re-authenticate era OAuth token refresh failed — re-authenticate, then re-enable Remote Control, e JWT refresh failed: no OAuth token — run /login era no OAuth token available for recovery (code <N>). I messaggi Claude.ai login expired, Claude.ai login was rejected e OAuth token unavailable sono stati aggiunti nella v2.1.225.

Prima della v2.1.238, Claude Code segnalava i casi che ora indicano Signed out of Claude come JWT refresh failed: no OAuth token — run /login, e interrompeva Remote Control con Claude.ai login expired — run /login to restore Remote Control non appena un aggiornamento dell'accesso non riceveva risposta.

Remote Control interrotto perché l'account con cui hai effettuato l'accesso è cambiato

Claude Code mostra questa riga durante una sessione Remote Control quando accedi a un account o a un'organizzazione claude.ai diversi su questa macchina. Hai effettuato il cambio al di fuori della sessione di Claude Code, ad esempio eseguendo /login in un altro terminale.

Una sessione Remote Control che hai avviato mentre avevi effettuato l'accesso tramite /login appartiene all'account e all'organizzazione claude.ai con cui avevi effettuato l'accesso in quel momento.

Remote Control disconnected — signed-in claude.ai account or organization changed on this machine — run /remote-control to start a session for the current account, or /login to switch back, then /remote-control

Claude Code interrompe la sessione Remote Control non appena claude.ai conferma che l'account o l'organizzazione è cambiato. La tua sessione locale continua a funzionare senza Remote Control.

Cosa fare:

• Esegui /remote-control per avviare una nuova sessione Remote Control con l'account o l'organizzazione corrente
• Per tornare indietro, esegui /login e accedi di nuovo all'account o all'organizzazione precedente. Poi esegui /remote-control.

Prima della v2.1.234, Claude Code non si accorgeva di quando passavi a un account o a un'organizzazione diversi al di fuori della sessione di Claude Code. Claude Code manteneva la sessione Remote Control connessa finché una richiesta successiva al server Remote Control non falliva con Remote Control server rejected the request (HTTP 404). Quell'errore poteva arrivare ore dopo il cambio.

Remote Control interrotto perché l'app che esegue la sessione è uscita o ha cambiato account

Quando l'app desktop di Claude o un IDE ospita la tua sessione, Claude Code ottiene il suo token di accesso da quell'app anziché da /login. Quando claude.ai rifiuta quel token, Claude Code ne chiede uno nuovo all'app. Se l'app risponde di non avere un accesso attivo, o di aver ora effettuato l'accesso con un account Claude diverso, Claude Code termina la sessione Remote Control e invia all'app una di queste righe:

Remote Control stopped — the app running this session is now signed in to a different Claude account
Remote Control stopped — the app running this session is signed out of Claude. Sign in there, then turn Remote Control back on

La tua sessione locale continua a funzionare senza Remote Control.

Cosa fare:

• Se l'app non ha un accesso attivo, accedi di nuovo, poi riattiva Remote Control nell'app
• Se l'app ha cambiato account, Claude Code non può continuare la sessione terminata con il nuovo account. Avvia una nuova sessione Remote Control con quell'account.

Prima della v2.1.238, in entrambi i casi Claude Code inviava all'app i messaggi run /login elencati in Remote Control non è riuscito ad aggiornare il tuo accesso.

Token OAuth revocato o scaduto

Il tuo accesso salvato non è più valido. Un token revocato significa che sei uscito ovunque o che un amministratore ha rimosso l'accesso; un token scaduto significa che l'aggiornamento automatico non è riuscito a metà sessione.

Entrambi i messaggi riportano un rifiuto restituito dall'API per una richiesta inviata da Claude Code. Quando l'accesso salvato è già stato cancellato dopo un aggiornamento non riuscito, vedi invece Accesso scaduto. Se ti autentichi con un token di lunga durata in CLAUDE_CODE_OAUTH_TOKEN, vedi gli stessi messaggi quando quel token scade o viene revocato.

OAuth token revoked · Please run /login
Please run /login · API Error: 401 OAuth token has expired ...

In modalità non interattiva (-p) e nell'Agent SDK, i messaggi sono i seguenti e il codice di errore strutturato è authentication_failed:

Failed to authenticate: OAuth token revoked. Please log in again or contact your administrator.
Failed to authenticate. API Error: 401 OAuth token has expired ...

Prima della v2.1.287, in modalità non interattiva e nell'Agent SDK, il messaggio per il token revocato era Your account does not have access to Claude. Please login again or contact your administrator.

Cosa fare:

• Esegui /login nel prompt di Claude Code per accedere di nuovo
• Se il tuo comando -p o il tuo programma Agent SDK usa un accesso salvato, esegui claude nello stesso ambiente, completa /login, poi esegui di nuovo il comando o il programma. Per le automazioni che non possono accedere in modo interattivo, autenticati con ANTHROPIC_API_KEY oppure genera un token di lunga durata con claude setup-token.
• Se ti autentichi con la variabile d'ambiente CLAUDE_CODE_OAUTH_TOKEN, Claude Code continua a inviare il valore che hai impostato dopo che una richiesta fallisce con un 401, anziché passare al token di un accesso salvato. /status mostra questa credenziale come una riga Auth token con valore CLAUDE_CODE_OAUTH_TOKEN. Genera un nuovo token con claude setup-token e riavvia con esso, oppure rimuovi la variabile ed esegui /login. Prima della v2.1.225, Claude Code poteva sostituire a metà sessione il valore della variabile con il token di accesso di breve durata di un accesso salvato, e la sessione tornava a fallire con errori 401 una volta scaduto quel token.
• Per richieste ripetute di accesso a ogni avvio, consulta i controlli dell'orologio di sistema e i passaggi di ripristino dell'archiviazione delle credenziali su macOS in Risoluzione dei problemi
• Per altri errori, inclusi 403 Forbidden e i problemi del browser con OAuth, consulta Accesso e autenticazione

API Error: 401 Invalid authentication credentials

L'API ha riconosciuto il formato della tua credenziale ma ha rifiutato l'account o l'organizzazione associati. Anthropic restituisce questo messaggio quando una credenziale è stata revocata di recente, quando un'organizzazione è stata disabilitata o ha rimosso il tuo accesso, oppure quando l'account stesso è stato disattivato, quindi la causa non è un token scaduto. La credenziale può essere il tuo accesso salvato o una ANTHROPIC_API_KEY approvata, e la soluzione è diversa, quindi inizia eseguendo /status per vedere quale è attiva.

Please run /login · API Error: 401 Invalid authentication credentials

Cosa fare:

• Se /status mostra una riga API key non contrassegnata come non in uso, una ANTHROPIC_API_KEY approvata è la credenziale attiva e ha la precedenza sul tuo accesso, quindi /login non la sostituisce. Ruota la chiave nella Claude Console, oppure torna al tuo abbonamento eseguendo unset ANTHROPIC_API_KEY, o in PowerShell Remove-Item Env:ANTHROPIC_API_KEY.
• Se /status mostra solo il tuo accesso, esegui /login una volta. Se la credenziale è stata revocata, un nuovo accesso la sostituisce.
• Se lo stesso messaggio ricompare per lo stesso account di accesso, l'account o l'organizzazione non è più attivo. Controlla l'account e l'organizzazione riportati da /status e chiedi all'amministratore della tua organizzazione di ripristinare l'accesso.
• Se ANTHROPIC_BASE_URL punta a un gateway LLM, il testo dopo 401 è il messaggio del tuo gateway e non di Anthropic, e /login non lo modifica. Correggi invece la credenziale che il tuo gateway si aspetta.

Accesso scaduto

Claude Code ha provato a rinnovare il tuo accesso claude.ai salvato e il servizio OAuth ha rifiutato il refresh token memorizzato, quindi Claude Code ha cancellato le credenziali salvate. Da quel momento, ogni richiesta al modello si interrompe localmente con questo messaggio prima di raggiungere l'API, perché solo /login può creare nuove credenziali.

Prima della v2.1.206, Claude Code inviava comunque la richiesta al modello con qualunque credenziale restasse nell'ambiente, e ogni modello falliva quindi con There's an issue with the selected model o con un 401 invece di una richiesta di accesso.

Login expired · Please run /login

In modalità non interattiva (-p) e nell'Agent SDK, il messaggio è il seguente e il codice di errore strutturato è authentication_failed:

Failed to authenticate: OAuth session expired and could not be refreshed

Questo stato non è lo stesso di Token OAuth revocato o scaduto. Quei messaggi riportano un rifiuto restituito dall'API. Claude Code stesso produce Login expired per un accesso che non è già riuscito a rinnovare, quindi non invia alcuna richiesta. Quando il rinnovo fallisce perché è l'account stesso a essere sospeso e non l'accesso a essere obsoleto, Claude Code mostra invece Il tuo account è sospeso.

Le sessioni autenticate con una chiave API, con CLAUDE_CODE_OAUTH_TOKEN o con un provider di terze parti non usano l'accesso salvato e non vedono mai questo messaggio.

Puoi verificare questo stato prima che una richiesta fallisca: /status mostra una riga Login con valore Expired — log in again, oltre all'organizzazione e all'email salvate per l'accesso scaduto. La riga compare solo quando l'accesso salvato è la tua credenziale attiva e non può più essere aggiornato. Le sessioni autenticate in altro modo non mostrano la riga, anche se resta salvato un accesso scaduto. Prima della v2.1.210, /status non dava alcuna indicazione in questo stato che fosse mai esistito un accesso, perché la credenziale cancellata non gli lasciava nulla da riportare.

Cosa fare:

• Esegui /login per accedere di nuovo. Riprovare senza accedere mostra lo stesso messaggio a ogni richiesta.
• Se accedi con il tuo account claude.ai in un'altra finestra di Claude Code, consulta Accesso non effettuato per sapere quando questa sessione inizia a usare quell'accesso da sola.
• In modalità non interattiva, esegui claude nello stesso ambiente, completa /login, poi esegui di nuovo il tuo comando. Per le automazioni che non possono accedere in modo interattivo, autenticati con ANTHROPIC_API_KEY oppure genera un token di lunga durata con claude setup-token.
• Se l'accesso continua a non riuscire, consulta Accesso e autenticazione

Impossibile aggiornare il tuo accesso perché un altro processo di Claude Code lo sta aggiornando

Questo messaggio non significa che il tuo accesso è stato rifiutato. Il tuo accesso claude.ai salvato era scaduto e doveva essere rinnovato. Un altro processo di Claude Code sulla stessa macchina deteneva il lock condiviso di aggiornamento, oppure è terminato lasciandolo attivo, e l'aggiornamento non ha fatto progressi mentre questa sessione attendeva. Claude Code interrompe la richiesta prima di inviarla:

Could not refresh your login because another Claude Code process is refreshing it (or exited mid-refresh) · Try again in a minute; if it keeps happening, close other Claude Code windows or sign in again with /login

In modalità non interattiva (-p) e nell'Agent SDK, il messaggio è il seguente e il codice di errore strutturato è server_error:

Failed to refresh OAuth token: another Claude Code process is refreshing it or exited mid-refresh. This is usually transient; retry in a minute, and if it persists close other Claude Code processes or sign in again

Le sessioni autenticate con una chiave API, con CLAUDE_CODE_OAUTH_TOKEN o con un provider di terze parti non usano l'accesso salvato e non vedono mai questo messaggio.

Cosa fare:

• Riprova tra un minuto. Se un altro processo completa prima l'aggiornamento, questa sessione usa l'accesso rinnovato.
• Se il messaggio continua a ripresentarsi, chiudi le altre finestre e gli altri processi di Claude Code, poi riprova.
• Se si ripresenta senza altri processi di Claude Code in esecuzione, esegui /login. Accedere di nuovo non attende il lock di aggiornamento.

Impossibile salvare il tuo accesso

Hai effettuato l'accesso con claude.ai, ma Claude Code non è riuscito a salvare l'accesso nel suo archivio delle credenziali, quindi l'accesso non è stato completato. Su macOS questo può accadere quando il portachiavi di login si blocca, ad esempio durante lo stop o l'inattività, dopo che Claude Code ha già letto o salvato credenziali al suo interno durante la stessa sessione.

Couldn't save your login. If your Mac's keychain is locked, unlock it and log in again.
Couldn't save your login. Try logging in again.

La prima forma compare su macOS e la seconda ovunque altrove. Un errore temporaneo dell'archivio delle credenziali, come un timeout o un archivio illeggibile, produce lo stesso messaggio.

Cosa fare:

• Su macOS, sblocca il portachiavi di login, poi esegui di nuovo /login
• Sulle altre piattaforme, esegui di nuovo /login
• Se l'accesso continua a non essere salvato, consulta Accesso non effettuato o token scaduto per il comando di sblocco del portachiavi e altri passaggi di ripristino dell'archiviazione delle credenziali

Impossibile avviare il server di callback OAuth

Quando /login, claude auth login o claude setup-token ti fa accedere tramite il browser, Claude Code apre una porta in ascolto su 127.0.0.1 in modo che il browser possa restituirgli il risultato dell'accesso. Questo messaggio indica che Claude Code non è riuscito ad aprire quella porta, e l'accesso si interrompe prima che compaia una finestra del browser o un URL di accesso:

Failed to start OAuth callback server: Failed to start server. Is port 0 in use?

Se il tuo messaggio termina con Is port 0 in use?, il tentativo di mettersi in ascolto sull'indirizzo di loopback IPv4 127.0.0.1 è fallito del tutto. Poiché l'errore si verifica prima che esista un URL di accesso, il flusso Paste code here if prompted non è disponibile come soluzione alternativa.

Cosa fare:

• Per accedere subito senza il listener locale: se usi un abbonamento claude.ai, esegui claude setup-token su una macchina in cui l'accesso funziona e imposta il token che stampa come CLAUDE_CODE_OAUTH_TOKEN su questa macchina. Altrimenti imposta ANTHROPIC_API_KEY con una chiave della Claude Console. Precedenza dell'autenticazione spiega come Claude Code sceglie tra le credenziali.
• Per usare invece l'accesso tramite browser su questa macchina, Claude Code deve potersi mettere in ascolto su 127.0.0.1. Se viene eseguito in una sandbox, verifica che il criterio della sandbox consenta l'ascolto su porte locali, poi esegui di nuovo /login. Se dovrebbe poterlo fare e continua a fallire, esegui /feedback in modo che la segnalazione includa i dettagli del tuo ambiente.

Accesso Claude non accettato

Hai provato ad avviare una sessione cloud e il server si è rifiutato di crearla con un 401: non ha accettato l'accesso Claude inviato da questa macchina, di solito perché l'accesso era scaduto o era stato revocato.

La prima parte della riga è il motivo fornito dal server, quando ne fornisce uno. Altrimenti la riga è:

Claude login not accepted · Run /login, then try again

Cosa fare:

• Esegui /login, completa l'accesso, poi avvia di nuovo la sessione

Gli artefatti richiedono un accesso claude.ai

Claude Code ha rifiutato la pubblicazione o la lettura di un artefatto perché la sessione non ha un accesso claude.ai utilizzabile per gli artefatti.

Ogni forma del messaggio inizia con le stesse parole, seguite da un rimedio che dipende da come si autentica la tua sessione. Senza credenziali concorrenti il messaggio è:

Artifacts need a claude.ai login. Run /login and select "Claude account with subscription", then retry — the "Anthropic Console account" option does not provide claude.ai credentials.

Cosa fare:

• Esegui /login e seleziona Claude account with subscription. L'opzione Anthropic Console account non fornisce credenziali claude.ai.
• Quando il messaggio indica una credenziale che ha la precedenza, come ANTHROPIC_API_KEY, un'impostazione apiKeyHelper o una chiave Console salvata da un precedente /login, rimuovila nel modo indicato dal messaggio, poi esegui /login
• Quando il messaggio dice che questa sessione remota si autentica tramite la macchina che l'ha avviata, accedi a claude.ai su quella macchina, poi riconnetti la sessione
• Quando il messaggio dice che la credenziale è fornita dall'ambiente host della sessione, non puoi modificarla in quella sessione; avvia una sessione con accesso effettuato a claude.ai
• Consulta Disponibilità per gli altri requisiti degli artefatti, come piano, provider del modello e criterio dell'organizzazione

Il criterio dell'amministratore richiede un accesso tramite Cloud gateway

Le impostazioni gestite di un amministratore su questa macchina impostano forceLoginMethod su "gateway" oppure impostano forceLoginGatewayUrl. A meno che tu non selezioni un provider cloud tramite una variabile come CLAUDE_CODE_USE_BEDROCK, Claude Code accetta quindi solo l'accesso tramite gateway delle app Claude. Vedi uno di due messaggi:

Not signed in to the Cloud gateway — run /login.

Le richieste al modello falliscono con questo messaggio quando la sessione non ha un accesso tramite gateway, ad esempio perché non hai eseguito /login da quando il criterio è arrivato sulla macchina.

Se la macchina contiene anche una credenziale emessa da Anthropic e le impostazioni gestite impostano forceLoginMethod o forceLoginOrgUUID, Claude Code termina invece all'avvio. Quella credenziale può essere una variabile ANTHROPIC_API_KEY o ANTHROPIC_AUTH_TOKEN, un'impostazione apiKeyHelper o una chiave API salvata da un precedente accesso alla Claude Console.

Il messaggio di avvio indica la credenziale con cui è configurata la sessione, dove è impostata e il passaggio per rimuoverla. Ad esempio, con una variabile ANTHROPIC_API_KEY impostata nella tua shell, il messaggio è:

Administrator policy requires a Cloud gateway sign-in on this machine, but this session is configured with an API key from ANTHROPIC_API_KEY, which a gateway machine does not accept.

To continue: unset ANTHROPIC_API_KEY (or run in a shell without it), then run claude and sign in with /login.

Cosa fare:

• Per Not signed in to the Cloud gateway, esegui /login e completa l'accesso nella schermata Cloud gateway
• Per il messaggio di avvio, rimuovi la credenziale seguendo i passaggi alla fine del messaggio
• Se ritieni che la macchina non debba richiedere il gateway, chiedi all'amministratore che la gestisce di rimuovere forceLoginMethod e forceLoginGatewayUrl dalle sue impostazioni gestite

Prima della v2.1.284, il messaggio di avvio elencava le credenziali possibili invece di indicare quella configurata. Iniziava con Administrator policy requires a Cloud gateway sign-in on this machine; the Anthropic-issued credential configured here (ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, or apiKeyHelper) is not used. Se vedi quella formulazione e non riesci a capire quale credenziale rimuovere, aggiorna alla v2.1.284 o successiva e avvia di nuovo claude.

Nella v2.1.265, una regressione mostrava il primo messaggio anche in alcune configurazioni con gateway LLM e proxy che si autenticano con una chiave API, apiKeyHelper o intestazioni personalizzate, anche senza alcun requisito dell'amministratore sulla macchina. Aggiorna alla v2.1.266 o successiva. Non è necessario modificare la tua configurazione.

Prima della v2.1.261, sulle macchine che impostano forceLoginMethod su "gateway", Claude Code usava un accesso salvato residuo invece di far fallire le richieste al modello, e segnalava una credenziale d'ambiente configurata con This machine's managed settings require a first-party login invece del messaggio di avvio.

Il tuo account è sospeso

L'account Claude associato al tuo accesso è stato sospeso. Claude Code mostra il primo messaggio quando prova a rinnovare il tuo accesso salvato e viene a sapere della sospensione, e il secondo quando un accesso che completi nel browser la segnala:

Your account is on hold and can't use Claude Code. View details or appeal: https://claude.ai/restricted
Your account is on hold and can't sign in to Claude Code. View details or appeal: https://claude.ai/restricted

Accedere di nuovo con lo stesso account non elimina il messaggio, perché la sospensione riguarda l'account e non l'accesso. In modalità non interattiva (-p) e nell'Agent SDK, il codice di errore strutturato è account_on_hold. Prima della v2.1.235, Claude Code segnalava un account sospeso come Login expired · Please run /login, i cui passaggi di ripristino non possono eliminare una sospensione.

Cosa fare:

• Apri il link nel messaggio per visualizzare i dettagli della sospensione o presentare ricorso
• Se hai un altro account Claude o una chiave API non interessati dalla sospensione, puoi continuare a lavorare mentre la sospensione viene risolta: esegui /login con quell'account, oppure imposta la chiave con ANTHROPIC_API_KEY

Accesso del profilo Anthropic scaduto

Claude Code si sta autenticando tramite un profilo di credenziali Anthropic la cui credenziale di accesso salvata è scaduta, e il profilo non contiene alcuna credenziale di aggiornamento che Claude Code possa usare per rinnovarla. Claude Code interrompe ogni richiesta localmente senza riprovare, perché un nuovo tentativo leggerebbe la stessa credenziale scaduta.

Anthropic profile login expired · Re-authenticate your Anthropic profile
Anthropic profile login expired · Run /login to use your claude.ai account instead, or re-authenticate the profile

Questo messaggio compare solo quando la credenziale attiva proviene da un profilo di credenziali Anthropic: uno che selezioni con la variabile d'ambiente ANTHROPIC_PROFILE, uno che Claude Code individua come profilo attivo nella tua directory di configurazione Anthropic, o uno che Claude Code ha scritto quando hai effettuato l'accesso senza una chiave API. Le sessioni che si autenticano con una chiave API, un bearer token come ANTHROPIC_AUTH_TOKEN o un provider di terze parti non vedono mai questo messaggio.

Su una macchina che offre l'accesso senza chiave, esegui /login, scegli l'account Anthropic Console e accedi di nuovo per rinnovare un profilo scritto dall'accesso Console senza chiave o da ant auth login della Claude Platform CLI. Claude Code sostituisce la credenziale scaduta in quel profilo. Per un profilo di federazione o uno creato da un altro strumento, /login non rinnova la credenziale. La forma che vedi dipende dal fatto che tu abbia selezionato il profilo o che Claude Code lo abbia individuato:

• Quando imposti ANTHROPIC_PROFILE esplicitamente, il messaggio termina con Re-authenticate your Anthropic profile.
• Quando Claude Code ha individuato il profilo dalla tua directory di configurazione, il messaggio propone /login, perché Claude Code dà a un /login funzionante la precedenza sul profilo individuato e poi si autentica invece con il tuo account claude.ai o Console. Prima della v2.1.234, Claude Code mostrava anche in questo caso la forma Re-authenticate your Anthropic profile.

Cosa fare:

• Accedi di nuovo al profilo, poi riprova: su una macchina che offre l'accesso senza chiave, esegui /login e scegli l'account Anthropic Console per un profilo scritto dall'accesso Console senza chiave o da ant auth login della Claude Platform CLI; per gli altri profili, usa lo strumento che li ha creati
• Se la credenziale del profilo è stata fornita da un amministratore, chiedigli di emetterne una nuova
• Esegui /status per verificare l'origine delle credenziali attiva e il nome del profilo
• Per smettere di usare il profilo, rimuovi ANTHROPIC_PROFILE se l'hai impostata, poi autenticati in un altro modo, ad esempio con /login o ANTHROPIC_API_KEY

Requisito di scope OAuth

Il token memorizzato è precedente a uno scope di permesso richiesto da una funzionalità più recente:

OAuth token does not meet scope requirement: user:profile

Cosa fare:

• Esegui /login per ottenere un nuovo token con gli scope attuali. Non è necessario uscire prima.

claude.ai ha rifiutato il token di sessione

Una richiesta di un connettore claude.ai è fallita perché claude.ai ha rifiutato il token del tuo accesso a Claude Code. Il token rifiutato è il tuo accesso, non l'autorizzazione propria del connettore in claude.ai, quindi autorizzare di nuovo il connettore non risolve il problema. In /mcp, il connettore appare come session token rejected e la sua vista dettagliata riporta:

claude.ai rejected the session token. Run /login, then reconnect.

Cosa fare:

• Esegui /login per accedere di nuovo
• Riconnetti il connettore da /mcp, oppure esegui /mcp reconnect <server>. Riconnettersi prima di accedere di nuovo lascia il connettore nello stesso stato. L'opzione Reconnect del pannello /mcp segnala your claude.ai session token was rejected; la forma digitata /mcp reconnect <server> segnala una riconnessione riuscita anche se il token è ancora rifiutato.

Prima della v2.1.222, Claude Code contrassegnava invece il connettore come bisognoso di autenticazione, indirizzandoti al flusso di autorizzazione del connettore anche se completarlo non risolveva lo stato.

Il server MCP richiede di accedere di nuovo

Un server MCP remoto ha rifiutato la credenziale in una chiamata a uno strumento a metà sessione, di solito perché un accesso o un token è scaduto o perché il token non ha un permesso necessario allo strumento. La chiamata allo strumento fallisce e /mcp contrassegna il server come bisognoso di autenticazione.

Per un server a cui accedi da Claude Code, incluso un connettore claude.ai, l'accesso è scaduto o è stato revocato:

MCP server "<name>" needs you to sign in again (run /mcp to re-authenticate)

Esegui /mcp, seleziona il server e accedi di nuovo dal suo menu.

Per un server configurato con uno script headersHelper, Claude Code ha già rieseguito l'helper e riprovato la chiamata una volta prima di mostrare questo messaggio:

MCP server "<name>" rejected the credential from its headersHelper (check the helper and run /mcp to reconnect, or to authenticate if the server also uses OAuth)

Verifica che l'helper restituisca una credenziale accettata dal server, poi riconnettiti da /mcp, che esegue di nuovo l'helper.

Per un server con un'intestazione Authorization statica nella sua configurazione:

MCP server "<name>" rejected the Authorization header in its config (update it, then run /mcp to reconnect)

Aggiorna il valore dell'intestazione dove è configurato il server, poi riconnettiti da /mcp.

Prima della v2.1.273, i casi di accesso scaduto, headersHelper e intestazione Authorization mostravano tutti MCP server "<name>" requires re-authorization (token expired).

Un server può anche rifiutare una chiamata a uno strumento con HTTP 403 insufficient_scope per chiederti di autorizzare uno scope, a volte uno che il tuo token elenca già. Il messaggio indica quello scope:

MCP server "<name>" needs additional permissions (scope: "<scope>") — run /mcp to re-authenticate

Esegui /mcp, seleziona il server e autenticati di nuovo dal suo menu.

Quando la configurazione del server non imposta né oauth.scopes né authServerMetadataUrl, Claude Code richiede lo scope indicato dal server. Con una delle due impostazioni, Claude Code richiede invece gli scope di quell'impostazione. Se hai fissato oauth.scopes, aggiungi lo scope mancante a quell'elenco prima di autenticarti di nuovo.

Prima della v2.1.274, questo caso mostrava il messaggio needs you to sign in again, e prima della v2.1.273 mostrava requires re-authorization (token expired) come gli altri casi.

URL del server MCP mancante o non valido

Claude Code si è rifiutato di avviare un accesso OAuth per un server MCP remoto perché l'url configurato del server non viene interpretato come URL. A meno che Claude Code non abbia un problema di configurazione più specifico da segnalare per il server, eseguire claude mcp login <name> nella tua shell stampa il rifiuto come:

Couldn't complete authentication for "<name>": This server's URL is missing or not a valid URL, so sign-in can't start. Fix the URL in its MCP config (or set the environment variable it uses) and try again.

Cosa fare:

• Imposta l'url della voce sull'endpoint reale del server dove il server è configurato, oppure imposta la variabile d'ambiente indicata dal suo riferimento ${VAR}, poi esegui di nuovo l'accesso.

Mancata corrispondenza dell'emittente nella risposta di autorizzazione

Durante un accesso OAuth MCP, il server di autorizzazione ha reindirizzato di nuovo a Claude Code con un parametro iss che non indica l'emittente che Claude Code si aspettava in base ai metadati OAuth del server. Un emittente errato in questo passaggio è il segno di un attacco di mix-up del server di autorizzazione, quindi Claude Code fa fallire l'accesso invece di scambiare il codice di autorizzazione. Claude Code mostra l'errore nel menu del server in /mcp dopo l'accesso tramite browser:

Issuer mismatch in authorization response (RFC 9207): expected "https://auth.example.com", received "https://other.example.com"

expected è l'emittente indicato nei metadati OAuth del server, e received è il valore iss contenuto nel reindirizzamento. Un accesso il cui reindirizzamento non contiene alcun parametro iss supera il controllo, a meno che i metadati del server non impostino authorization_response_iss_parameter_supported, nel qual caso Claude Code fa fallire l'accesso.

Cosa fare:

• Riprova l'accesso da /mcp
• Se l'errore si ripete, segnalalo al gestore del server. La correzione è lato server: il server di autorizzazione deve restituire nel parametro iss lo stesso emittente che dichiara nei suoi metadati
• Per connetterti mentre il server viene corretto, avvia Claude Code con MCP_SDK_GENERATION=v1, il cui runtime non esegue questo controllo. Questo rimuove una protezione contro gli attacchi di mix-up, quindi preferisci la correzione lato server

Prima della v2.1.232, Claude Code usava il runtime v2 solo in un rilascio graduale o quando impostavi MCP_SDK_GENERATION=v2.

Rifiuto di inviare credenziali a un endpoint token non https

Con il runtime v2, Claude Code invia una richiesta di token OAuth MCP solo a un endpoint token servito tramite HTTPS oppure su localhost, 127.0.0.1 o ::1. Questo messaggio indica che l'endpoint token del server non è né l'uno né l'altro, quindi Claude Code si è fermato prima di inviare la richiesta. Ciò accade dopo l'accesso tramite browser, quindi il passaggio nel browser riesce prima, e di nuovo ogni volta che Claude Code aggiorna il token del server.

Nella sua forma completa, il messaggio proviene dall'SDK MCP e cita l'endpoint token rifiutato. Nel log di debug, segue Error during auth completion: per un accesso o Token refresh failed: per un aggiornamento. Nella tua shell, claude mcp login <name> lo stampa dopo Couldn't complete authentication for "<name>":, e in una sessione /mcp lo mostra nel menu del server:

Refusing to send credentials to non-https token endpoint 'http://192.168.1.50:8123/oauth/token'. OAuth token requests MUST use TLS (localhost / 127.0.0.1 / ::1 are exempt).

Claude Code considera potenzialmente segreto un URL del server che contiene una query string o un segmento di percorso lungo e dall'aspetto casuale. Per un server di questo tipo, oscura gli errori di accesso generati dall'SDK MCP prima di mostrarli o registrarli nei log. Questo errore appare allora come un nome breve che può cambiare tra una release e l'altra, come io, seguito da from the MCP SDK for e dall'URL del server oscurato. Anche gli altri errori dell'SDK MCP assumono lì la stessa forma. Il messaggio oscurato può corrispondere a questo errore solo quando l'endpoint token del server è un semplice http:// su un indirizzo diverso da localhost, 127.0.0.1 o ::1.

Cosa fare:

• Servi quell'endpoint token tramite HTTPS, ad esempio mettendo il server dietro un reverse proxy o un tunnel che termina TLS e configurando il server in modo che dichiari l'indirizzo https://
• Per connetterti senza modificare il server, avvia Claude Code con MCP_SDK_GENERATION=v1, il cui runtime non applica questa regola e invia la richiesta di token tramite HTTP semplice. Questa scelta dura finché non esci e si applica a ogni server. Il runtime v1 salta anche il controllo dell'emittente, quindi preferisci servire l'endpoint tramite HTTPS

Credenziali AWS scadute o non valide

Il tuo token di sessione AWS è scaduto o è stato rifiutato. Questo messaggio compare in caso di 401 da Claude Platform on AWS o dall'endpoint Mantle, che è il modo in cui questi provider segnalano un token di sicurezza scaduto.

Il suggerimento di azione nella parte centrale varia in base alla tua configurazione. La parte stabile è quella iniziale, AWS credentials expired or invalid:

AWS credentials expired or invalid · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · API Error: 401 ...

Prima della v2.1.273, questo messaggio compariva solo quando awsAuthRefresh era configurato.

Cosa fare:

• Se il suggerimento dice che le credenziali sono gestite da questo ambiente, l'app che ha avviato Claude Code possiede la credenziale e gli altri passaggi qui non si applicano: riprova, oppure contatta il tuo amministratore
• Se awsAuthRefresh è impostato, esegui il comando indicato nel messaggio, come aws sso login --profile myprofile, in un altro terminale e completa l'accesso nel browser, poi riprova. Altrimenti aggiorna tu stesso la credenziale AWS che usi: il tuo accesso SSO, le chiavi di accesso, la chiave API o il token del proxy
• Con awsAuthRefresh impostato in una sessione interattiva, puoi invece eseguire /login, scegliere 3rd-party platform, poi selezionare Claude Platform on AWS · refresh credentials in Using 3rd-party platforms per eseguire lo stesso comando senza riavviare Claude Code. Consulta Configurare le credenziali AWS
• Se l'errore si ripete dopo che il comando di aggiornamento è riuscito, verifica che l'identità sia valida al di fuori di Claude Code con aws sts get-caller-identity nella stessa shell e con lo stesso profilo

Autenticazione AWS non riuscita

Il tuo provider AWS ha restituito un 403, oppure Amazon Bedrock ha restituito un 401.

Amazon Bedrock segnala un token di sicurezza scaduto come 403, ma un 403 è anche il modo in cui segnala un rifiuto di autorizzazione, come un AccessDeniedException dovuto a un permesso IAM mancante. Claude Code non è in grado di distinguere queste due cause.

Anche un 401 da Amazon Bedrock finisce qui anziché in Credenziali AWS scadute o non valide, perché Amazon Bedrock non segnala un token scaduto come 401. Un 401 da quell'endpoint deriva in genere da qualcos'altro nel percorso della richiesta, come un proxy aziendale.

Un aggiornamento delle credenziali risolve un token scaduto ma non può risolvere le altre cause, quindi il messaggio propone entrambe le soluzioni:

AWS authentication failed · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · if credentials are current, check AWS permissions and model access · API Error: 403 ...

Il suggerimento di azione nella parte centrale varia in base alla tua configurazione. La parte stabile è quella iniziale, AWS authentication failed.

Quando il 403 è la risposta di Amazon Bedrock per indicare che non hai accesso al modello con l'ID modello specificato, il suggerimento ti dice invece di abilitare il modello per il tuo account e la tua regione nella console di Amazon Bedrock.

Prima della v2.1.273, questo messaggio compariva solo quando awsAuthRefresh era configurato.

Cosa fare:

• Se il suggerimento dice che le credenziali sono gestite da questo ambiente, l'app che ha avviato Claude Code possiede la credenziale e gli altri passaggi qui non si applicano: riprova, oppure contatta il tuo amministratore
• Aggiorna le tue credenziali AWS nel caso in cui la causa sia una credenziale scaduta: esegui il comando awsAuthRefresh indicato nel messaggio quando ne è impostato uno, oppure aggiorna tu stesso il tuo accesso SSO, le chiavi di accesso, la chiave API o il token del proxy
• Se le tue credenziali sono aggiornate, verifica che i permessi IAM indicati in Configurazione IAM siano associati all'identità che stai usando e che il modello selezionato sia abilitato per il tuo account e la tua regione
• Esegui aws sts get-caller-identity per verificare quale identità usano le tue richieste

Credenziali Google Cloud scadute o non valide

Le tue credenziali Google Cloud per Agent Platform di Google Cloud sono scadute o sono state rifiutate: la richiesta ha restituito un 401, che è il modo in cui Agent Platform segnala la scadenza delle credenziali.

Il suggerimento di azione nella parte centrale varia in base alla tua configurazione. La parte stabile è quella iniziale, Google Cloud credentials expired or invalid:

Google Cloud credentials expired or invalid · refresh your Google Cloud credentials (application default sign-in, or the key file in GOOGLE_APPLICATION_CREDENTIALS) and retry · API Error: 401 ...

Cosa fare:

• Se il suggerimento dice che le credenziali sono gestite da questo ambiente, l'app che ha avviato Claude Code possiede la credenziale e gli altri passaggi qui non si applicano: riprova, oppure contatta il tuo amministratore
• Se ti autentichi con le credenziali predefinite dell'applicazione, esegui il comando gcpAuthRefresh indicato nel messaggio, oppure gcloud auth application-default login, e completa l'accesso, poi riprova
• Se instradi tramite un gateway LLM con CLAUDE_CODE_SKIP_VERTEX_AUTH impostata, aggiorna il token del gateway in ANTHROPIC_AUTH_TOKEN o ANTHROPIC_CUSTOM_HEADERS, poi riprova
• Se ti autentichi con un file di chiave di un service account, verifica che GOOGLE_APPLICATION_CREDENTIALS punti a una chiave valida. Consulta Configurare le credenziali GCP
• Se l'errore si ripete dopo un aggiornamento, verifica che l'identità funzioni al di fuori di Claude Code con gcloud auth application-default print-access-token nella stessa shell

Prima della v2.1.273, un 401 da Agent Platform mostrava invece il messaggio generico Please run /login o Failed to authenticate, che non può aggiornare le credenziali Google Cloud.

Autenticazione Google Cloud non riuscita

Agent Platform di Google Cloud ha restituito un 403, che usa per i rifiuti di autorizzazione anziché per le credenziali scadute. Di solito all'identità con cui ti autentichi manca un permesso IAM, oppure il modello non è abilitato per il tuo progetto.

Il suggerimento di azione al centro varia in base alla tua configurazione. La parte stabile è l'iniziale Google Cloud authentication failed:

Google Cloud authentication failed · refresh your Google Cloud credentials (application default sign-in, or the key file in GOOGLE_APPLICATION_CREDENTIALS) and retry · if credentials are current, check GCP IAM permissions and Vertex AI model access · API Error: 403 ...

Cosa fare:

• Se il suggerimento indica che le credenziali sono gestite da questo ambiente, la credenziale appartiene all'app che ha avviato Claude Code e gli altri passaggi qui non si applicano: riprova oppure contatta il tuo amministratore
• Verifica che i ruoli indicati in Configurazione IAM siano concessi all'identità con cui ti autentichi
• Verifica che il modello sia abilitato per il tuo progetto. Consulta Richiedere l'accesso al modello

Prima della v2.1.273, un 403 da Agent Platform mostrava invece il messaggio generico Please run /login o Failed to authenticate, che non può aggiornare le credenziali Google Cloud.

Autenticazione Microsoft Foundry non riuscita

Microsoft Foundry ha restituito un 401 o un 403: la credenziale Azure nella richiesta è stata rifiutata, oppure l'identità associata non ha accesso alla risorsa Foundry. /login non può generare credenziali Azure. Il suggerimento di azione al centro varia in base alla tua configurazione. La parte stabile è l'iniziale Microsoft Foundry authentication failed:

Microsoft Foundry authentication failed · refresh your Foundry credential (ANTHROPIC_FOUNDRY_AUTH_TOKEN, ANTHROPIC_FOUNDRY_API_KEY, Azure sign-in for Entra, or your proxy token) and retry · if credentials are current, check access to the Foundry resource · API Error: 401 ...

Cosa fare:

• Se il suggerimento indica che le credenziali sono gestite da questo ambiente, la credenziale appartiene all'app che ha avviato Claude Code e gli altri passaggi qui non si applicano: riprova oppure contatta il tuo amministratore
• Aggiorna la credenziale che hai configurato in Configurare le credenziali Azure: ruota ANTHROPIC_FOUNDRY_API_KEY, genera un nuovo ANTHROPIC_FOUNDRY_AUTH_TOKEN oppure esegui az login in modo che la catena di credenziali predefinita di Microsoft Entra possa accedere di nuovo
• Se la credenziale è aggiornata, verifica che l'identità abbia accesso alla risorsa Foundry. Consulta Configurazione RBAC di Azure

Prima della v2.1.273, un 401 o un 403 da Microsoft Foundry mostrava invece il messaggio generico Please run /login o Failed to authenticate, che non può aggiornare le credenziali Azure.

Impossibile caricare le credenziali AWS o Google Cloud

Claude Code non è riuscito a ottenere credenziali utilizzabili dalla catena di provider di credenziali AWS o dalle credenziali predefinite dell'applicazione Google sulla macchina su cui è in esecuzione, quindi nessuna richiesta ha raggiunto il tuo provider cloud. Claude Code svuota le credenziali nella cache e riprova due volte prima di mostrare questo messaggio. Il dettaglio dopo il · indica la causa specifica, ad esempio una sessione SSO scaduta, credenziali predefinite dell'applicazione mancanti segnalate come Could not load the default credentials, oppure un accesso revocato segnalato come invalid_grant:

API Error: Could not load AWS credentials · Could not load credentials from any providers. Check or refresh your AWS credentials and try again.
API Error: Could not load Google Cloud credentials · invalid_grant. Check or refresh your Google Cloud credentials and try again.

In modalità non interattiva con -p e nell'Agent SDK, il codice di errore strutturato è cloud_credential_error. Prima della v2.1.267, il messaggio mostrava solo il testo di dettaglio dopo API Error: e il codice strutturato era server_error o unknown.

Cosa fare:

• Esegui il comando di accesso del tuo provider, ad esempio aws sso login --profile myprofile o gcloud auth application-default login, quindi riprova. Credenziali Bedrock, Agent Platform o Foundry non caricate mostra come verificare le credenziali al di fuori di Claude Code
• Se il dettaglio riporta AWS default-chain credential resolve timed out, la catena si è bloccata anziché fallire, quindi segui invece Timeout nella risoluzione delle credenziali della catena predefinita AWS

Timeout nella risoluzione delle credenziali della catena predefinita AWS

La catena di provider di credenziali predefinita AWS non ha prodotto credenziali entro 60 secondi, quindi Claude Code ha interrotto la risoluzione e ha fatto fallire la richiesta. Questo timeout è una delle cause di Impossibile caricare le credenziali AWS o Google Cloud. L'errore riguarda la risoluzione locale delle credenziali: la richiesta non ha mai raggiunto Amazon Bedrock, Claude Platform on AWS o l'endpoint Mantle. Claude Code svuota la sua cache delle credenziali e riprova prima che questo errore venga mostrato, quindi quando lo vedi la catena si è bloccata in tentativi ripetuti.

API Error: Could not load AWS credentials · AWS default-chain credential resolve timed out. Check or refresh your AWS credentials and try again.

Le cause comuni sono un comando credential_process nel tuo profilo AWS che attende un input che non può ricevere, e un container o una VM il cui servizio di metadati dell'istanza (IMDS) non risponde mai alla verifica della catena.

Prima della v2.1.267, il messaggio riportava API Error: AWS default-chain credential resolve timed out. Prima della v2.1.207, una catena bloccata lasciava la richiesta in attesa indefinitamente anziché farla fallire.

Cosa fare:

• Esegui aws sts get-caller-identity nella stessa shell con lo stesso AWS_PROFILE. Se si blocca anche questo, correggi il profilo; un comando credential_process che chiede input in modo interattivo è una causa comune.
• Completa il passaggio di accesso prima di avviare Claude Code, ad esempio aws sso login --profile myprofile
• Se la tua catena esegue un accesso interattivo che richiede legittimamente più di 60 secondi, come SSO con MFA tramite un wrapper come aws-vault, aumenta il limite in millisecondi con CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS

Timeout della verifica della configurazione di Bedrock in attesa di AWS

Una chiamata ad AWS durante la verifica delle credenziali della procedura guidata di configurazione di Bedrock, come la ricerca delle credenziali o il controllo dell'identità, non è terminata entro il limite di 60 secondi. La procedura guidata smette di attendere e fa fallire il passaggio di verifica:

Timed out after 60s waiting for AWS. Check your network and proxy settings; if a credential helper needs longer to prompt you, raise CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS.

Il numero riflette il tuo limite: 60 secondi per impostazione predefinita, oppure il valore che hai impostato in CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS.

Le cause comuni sono una rete o un proxy che blocca le richieste ad AWS, incluso l'aggiornamento del token SSO, e un helper delle credenziali ancora in attesa di un input che non puoi vedere. Aumenta il limite solo quando l'helper ha legittimamente bisogno di più tempo.

Una singola richiesta ad AWS bloccata può anche fallire per il proprio timeout per richiesta, che mostra un messaggio più breve nello stesso passaggio:

A request to AWS timed out. Check your network and proxy settings, then try again.

Quando gli stessi timeout si verificano nel passaggio di fissaggio del modello, la procedura guidata contrassegna un modello come unreachable anziché mostrare uno dei due messaggi.

Cosa fare:

• Esegui aws sts get-caller-identity nella stessa shell. Se si blocca anche questo, il blocco è al di fuori di Claude Code, nella tua rete, nel tuo proxy o nell'helper delle credenziali del tuo profilo AWS; risolvi prima quello.
• Completa qualsiasi accesso interattivo prima di aprire la procedura guidata, ad esempio aws sso login --profile myprofile
• Se un helper delle credenziali nel tuo profilo AWS ha legittimamente bisogno di più di 60 secondi per chiederti l'input, aumenta il limite in millisecondi con CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS

Sessione del gateway cloud scaduta

Hai effettuato l'accesso tramite un gateway delle app Claude e la sessione del gateway salvata su questa macchina è scaduta e non è stato possibile rinnovarla, oppure il gateway non la accetta più, ad esempio dopo la sostituzione del segreto JWT del gateway. Se vedi questa riga quando avvii claude in modo interattivo, la sessione si è aperta senza accesso al gateway:

Cloud gateway session expired — run /login to reconnect.

La stessa riga può comparire durante la sessione quando la credenziale del gateway scade e Claude Code non riesce a rinnovarla.

In un'esecuzione non interattiva, in una sessione in background o in un'altra sessione non presidiata, oppure in un sottocomando di claude diverso da claude auth, Claude Code termina invece con questo messaggio quando il gateway non accetta più la sessione:

Cloud gateway <url> no longer accepts this session. Start `claude` and sign in again with /login.

Cosa fare:

• Esegui /login nella sessione e completa l'accesso dal browser
• Per un avvio non interattivo, avvia claude nello stesso ambiente, esegui /login, quindi esegui di nuovo il tuo comando

Accesso scaduto in attesa che tu proseguissi

Durante un accesso tramite un gateway delle app Claude, il gateway ha indicato l'account che ha effettuato l'accesso e Claude Code ti ha chiesto di confermarlo prima di salvare la credenziale. Hai lasciato la conferma aperta oltre la scadenza dell'accesso stesso e il gateway non ha emesso alcun refresh token in grado di rinnovarlo, quindi Claude Code non ha memorizzato nulla quando hai proseguito:

Sign-in timed out while waiting for you to continue. Try again.

Cosa fare:

• Esegui di nuovo /login e conferma l'account prima che l'accesso scada

Il gateway ha rifiutato la richiesta

Hai effettuato l'accesso tramite un gateway delle app Claude e una richiesta ha restituito un 403: il gateway, o il servizio upstream dietro di esso, l'ha rifiutata. Accedere di nuovo non cambia un rifiuto, quindi il messaggio ti indirizza all'amministratore del gateway:

Gateway refused the request · signing in again won't change this — check with your gateway administrator · API Error: 403 ...

Cosa fare:

• Chiedi all'amministratore del gateway di esaminare la richiesta. La parte finale API Error: contiene il rifiuto restituito dal gateway
• Per gli amministratori: una regola di controllo degli accessi sul gateway restituisce un 403 che il log di audit registra con il relativo motivo, e il rifiuto di autorizzazione di un upstream viene inoltrato secondo quanto descritto in Messaggi di errore upstream

Prima della v2.1.273, un 403 in una sessione del gateway mostrava invece il messaggio generico Please run /login o Failed to authenticate, e accedere di nuovo non eliminava il rifiuto.

Errori di rete e connessione

La maggior parte di questi errori significa che una richiesta di rete da Claude Code non ha raggiunto la sua destinazione, oppure qualcosa tra Claude Code e l'API ha alterato la risposta durante il percorso; quando una voce ha anche una causa locale, come un'archivio fallito, il corpo lo specifica. Di solito originano dalla tua rete locale, proxy o firewall, oppure dalla politica di rete dell'ambiente cloud.

Unable to connect to API

La connessione TCP all'API non è riuscita o non si è mai completata. Per i codici di errore di connessione comuni, il nome del messaggio specifica il tipo di errore e mantiene il codice tra parentesi:

Unable to connect to API. Check your internet connection
Connection refused — a firewall or proxy may be blocking it (ConnectionRefused)
Can't reach the API server — check your internet or DNS (ENOTFOUND)
No internet route — check your connection or VPN (EHOSTUNREACH)
Couldn't connect through your proxy (ERR_PROXY_TUNNEL) — the proxy refused the tunnel: check its credentials and that it allows this host
Connection dropped (ECONNRESET)
Request timed out. Check your internet connection and proxy settings

Un codice che Claude Code non riconosce appare come Unable to connect to API seguito dal codice tra parentesi. Alcuni di questi messaggi possono mostrare più di un codice: Connection refused può mostrare ConnectionRefused o ECONNREFUSED, ad esempio, e Can't reach the API server può mostrare ENOTFOUND o FailedToOpenSocket.

Prima della v2.1.227, ognuno di questi messaggi codificati leggeva Unable to connect to API seguito dal codice, ad esempio Unable to connect to API (ECONNREFUSED).

Le cause comuni includono nessun accesso a Internet, una VPN che blocca api.anthropic.com, o un proxy aziendale richiesto che non è configurato.

Cosa fare:

• Conferma di poter raggiungere l'host API dalla stessa shell eseguendo curl -I https://api.anthropic.com. Su Windows PowerShell usa curl.exe -I https://api.anthropic.com in modo che l'alias Invoke-WebRequest integrato non sia utilizzato.
• Se sei dietro un proxy aziendale, imposta HTTPS_PROXY prima di avviare Claude Code e vedi Network configuration
• Se instrada attraverso un gateway LLM o un relay, imposta ANTHROPIC_BASE_URL al suo indirizzo. Vedi Connect Claude Code to an LLM gateway per la configurazione.
• Assicurati che il tuo firewall consenta gli host elencati in Network access requirements
• I guasti intermittenti vengono ritentati automaticamente; i guasti persistenti indicano un problema di rete locale

Se curl ha successo ma Claude Code continua a fallire, la causa è solitamente qualcosa tra il runtime e la rete piuttosto che la rete stessa:

• Controlla se ANTHROPIC_BASE_URL è impostato eseguendo echo $ANTHROPIC_BASE_URL, o echo $env:ANTHROPIC_BASE_URL in PowerShell, e cercalo nel blocco env dei tuoi settings files. Quando è impostato, Claude Code invia le richieste del modello a quell'indirizzo invece di api.anthropic.com, quindi un valore residuo che punta a un proxy locale o gateway che non è più in esecuzione produce Connection refused anche se curl raggiunge l'API. Rimuovilo dal tuo profilo shell o dalle impostazioni e avvia Claude Code da un nuovo terminale.
• Su Linux e WSL, controlla /etc/resolv.conf per un nameserver non raggiungibile. WSL in particolare può ereditare un resolver rotto dall'host.
• Su macOS, un client VPN che è stato disconnesso o disinstallato può lasciare dietro un'interfaccia tunnel o una regola di routing. Controlla ifconfig per interfacce utun stantie e rimuovi l'estensione di rete della VPN in Impostazioni di Sistema.
• Docker Desktop e runtime di container simili possono intercettare il traffico in uscita. Chiudili e riprova per escludere questa possibilità.

Unable to connect to Anthropic services

Durante la configurazione della prima esecuzione, Claude Code verifica di poter raggiungere api.anthropic.com e platform.claude.com prima di mostrare il passaggio di accesso. Quando uno dei controlli fallisce, Claude Code stampa il motivo ed esce.

Unable to connect to Anthropic services
Failed to connect to api.anthropic.com: ECONNREFUSED
Connection to api.anthropic.com timed out after 10 seconds
A proxy is configured via HTTPS_PROXY. Check that it allows connections to the host above.

Claude Code invia il controllo attraverso la stessa proxy configuration delle richieste API e assegna a ogni sonda 10 secondi. Quando la sonda fallita è passata attraverso un proxy, il messaggio nomina la variabile di ambiente che l'ha configurata, come HTTPS_PROXY. Prima della v2.1.222, il controllo utilizzava un diverso trasporto proxy senza timeout: dietro un URL proxy con lo schema https://, potrebbe bloccarsi su Checking connectivity... indefinitamente e poi fallire anche se le richieste API attraverso lo stesso proxy hanno successo.

Claude Code salta questo controllo quando un managed settings file, MDM policy, o policy helper imposta forceLoginMethod a "gateway", o imposta forceLoginGatewayUrl senza forceLoginMethod. Con entrambe le configurazioni, Claude Code apre il passaggio di accesso sulla schermata Cloud gateway piuttosto che su un metodo di accesso Anthropic. Claude Code salta anche il controllo quando una fonte di managed settings sulla macchina esiste ma non può essere letta, poiché quella fonte potrebbe contenere la configurazione del gateway. Prima della v2.1.247, Claude Code eseguiva il controllo anche sotto questa configurazione e usciva con questo errore quando gli endpoint di Anthropic non erano raggiungibili.

Cosa fare:

• Se il messaggio nomina una variabile proxy, controlla che il suo valore punti al proxy giusto e chiedi al tuo team di rete di consentire connessioni HTTPS attraverso di esso all'host nel messaggio. Vedi Network configuration.
• Lavora attraverso i controlli in Unable to connect to API. Il test curl e la guida del firewall lì si applicano anche a questo controllo.
• Se la tua rete è aperta e il guasto persiste, Claude Code potrebbe non essere disponibile nel tuo paese

Socket is closed

Socket is closed significa che la connessione che trasporta una risposta in streaming è stata chiusa mentre la risposta stava ancora arrivando. La causa più comune è un proxy aziendale su Windows che interrompe un tunnel stabilito a metà risposta.

A seconda di quanto la risposta era progredita, Claude Code ritenta la richiesta, mantiene ciò che Claude ha prodotto, o termina il turno. Vedi Automatic retries.

Prima della v2.1.214, Claude Code non ritentava questo guasto e il turno si fermava con un errore contenente Socket is closed.

Cosa fare:

• Se vedi questo errore, aggiorna a v2.1.214 o successivo con claude update, quindi invia di nuovo il tuo messaggio
• Se i turni continuano a fallire dietro lo stesso proxy dopo l'aggiornamento, lavora attraverso Unable to connect to API e controlla la configurazione del proxy in Network configuration

API returned an empty or malformed response

Claude Code mostra questo errore quando il suo ritentativo non in streaming di una richiesta in streaming fallita ottiene uno stato HTTP di successo ma il corpo non è un messaggio API Claude: comunemente una pagina di errore HTML o di accesso, un corpo vuoto, o JSON in un altro formato. Un proxy, gateway, o pagina di accesso di rete che risponde al posto dell'API è la solita fonte. Claude Code non ritenta la richiesta e il turno termina con questo errore.

API returned an empty or malformed response (HTTP 200) — check for a proxy or gateway intercepting the request.

Dopo quell'apertura, il messaggio segnala ciò che è tornato e quale richiesta ha fallito:

• Una clausola Response: con il tipo di contenuto, il tipo di corpo, come body is an HTML page o empty body, la sua dimensione in byte, e se la risposta ha portato un id di richiesta Anthropic. Quando la risposta nomina un server riconoscibile, come nginx o cloudflare, o porta intestazioni intermediarie, come cf-ray o via, la clausola elenca anche quelli.
• Una frase che nomina l'id della richiesta in streaming fallita e il guasto che ha attivato il ritentativo. Quando uno stream si era aperto prima del guasto, segnala anche quanti eventi di stream sono arrivati e, se ce ne sono stati, quanto tempo lo stream era stato silenzioso quando il tentativo è fallito.

Prima della v2.1.234, il messaggio terminava dopo intercepting the request.

Prima della v2.1.271, una risposta che portava un messaggio API valido sotto un tipo di contenuto non JSON come text/plain terminava anche il turno con questo errore. Alcuni gateway LLM utilizzano quel tipo di contenuto per la risposta non in streaming.

Cosa fare:

• Leggi la clausola Response: per vedere quale sistema ha risposto. Un corpo HTML, nessun id di richiesta Anthropic, o un server nominato come nginx o cloudflare significa che qualcosa tra Claude Code e l'API ha risposto al suo posto
• Se instrada attraverso un LLM gateway, testa il percorso con una richiesta diretta e correggi l'hop che restituisce la risposta non-API
• Su una rete con una pagina di accesso, come Wi-Fi ospite, completa l'accesso in un browser, quindi riprova
• Se solo il percorso non in streaming attraverso il tuo gateway è rotto, imposta CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1 per disattivare questo fallback, tranne quando l'endpoint di streaming stesso restituisce 404, dove Claude Code continua comunque a fare fallback

Streaming response ended before any complete data was received

Una risposta in streaming dal tuo provider di modelli è stata completata senza fornire dati utilizzabili, quindi Claude Code ha reinviato la richiesta senza streaming per terminare il turno. Claude Code mostra l'avviso una volta per sessione, solo in sessioni interattive. Prima della v2.1.239, Claude Code ritentava silenziosamente senza streaming.

Streaming response ended before any complete data was received. Retrying without streaming. If this keeps happening, check any proxy or gateway between Claude Code and your model provider.

Claude Code invia ogni richiesta interessata due volte: il tentativo di streaming vuoto e il ritentativo. La causa solita è un proxy o gateway che consuma o trasforma il corpo della risposta in streaming durante il percorso di ritorno.

Cosa fare:

• Configura qualsiasi proxy o gateway tra Claude Code e il tuo provider di modelli per passare i corpi della risposta in streaming e le loro intestazioni senza modifiche
• Su Amazon Bedrock, vedi Streaming errors behind a gateway or proxy per i requisiti di intestazione e corpo

Bedrock streaming response has an unexpected content-type

Un gateway o proxy tra Claude Code e Amazon Bedrock sta trasformando il corpo della risposta in streaming o la sua intestazione Content-Type. Amazon Bedrock trasmette le risposte come application/vnd.amazon.eventstream. Piuttosto che decodificare un corpo che non può leggere, Claude Code rifiuta una risposta in streaming riuscita che segnala un content-type diverso. Claude Code non ritenta la richiesta.

Bedrock streaming response has content-type "text/event-stream"; expected "application/vnd.amazon.eventstream". A gateway or proxy between Claude Code and Bedrock is likely transforming the response body — Bedrock's binary event-stream format must be passed through unmodified. Set CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1 to suppress this check while the gateway is being fixed.

Prima della v2.1.208, la stessa configurazione errata è emersa come API Error: Truncated event message received dopo che l'intera risposta era stata memorizzata nel buffer.

Cosa fare:

• Configura il gateway per passare il corpo della risposta InvokeModelWithResponseStream e la sua intestazione Content-Type senza modifiche. Un intermediario che ri-emette lo stream come server-sent events è una causa comune.
• Impostare CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1 nasconde questo errore, ma Claude Code non decodifica un corpo binario sotto un'intestazione riscritta, quindi quelle richieste ricadono in un percorso più lento non in streaming. Vedi Streaming errors behind a gateway or proxy.

SSL certificate errors

Un proxy o appliance di sicurezza sulla tua rete sta intercettando il traffico TLS con il suo certificato, e Claude Code non lo ritiene attendibile.

Unable to connect to API: SSL certificate verification failed (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). The certificate comes from an authority Claude Code doesn't trust, usually a TLS-inspecting corporate proxy or a gateway signed by a private CA: set NODE_EXTRA_CA_CERTS to that CA bundle, or add it to the system certificate store · see https://code.claude.com/docs/en/network-config
Unable to connect to API: Self-signed certificate detected (SELF_SIGNED_CERT_IN_CHAIN). The certificate comes from an authority Claude Code doesn't trust, usually a TLS-inspecting corporate proxy or a gateway signed by a private CA: set NODE_EXTRA_CA_CERTS to that CA bundle, or add it to the system certificate store · see https://code.claude.com/docs/en/network-config

Prima della v2.1.273, entrambi i messaggi terminavano a Check your proxy or corporate SSL certificates, senza il codice OpenSSL o il suggerimento NODE_EXTRA_CA_CERTS.

A partire dalla v2.1.199, un guasto di convalida del certificato non viene ritentato, quindi questo errore appare al primo tentativo invece che dopo il retry budget completo. Le versioni precedenti spendevano alcuni minuti ritentando prima di mostrarlo. Le condizioni TLS transitorie, come un timeout di handshake, continuano a ritentare.

Durante /login e il controllo di connettività all'avvio, lo stesso guasto produce un messaggio diverso:

SSL certificate error (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). If you are behind a corporate proxy or TLS-intercepting firewall, set NODE_EXTRA_CA_CERTS to your CA bundle path, or ask IT to allowlist *.anthropic.com. Run `claude doctor` for details.

Su Amazon Bedrock, le richieste che Claude Code stesso invia ad AWS, come le chiamate di credenziale di ruolo STS e SSO, la scoperta del modello, e i controlli della procedura guidata di configurazione, dipendono dalla stessa configurazione del certificato. Vedi Certificate errors behind a TLS-inspecting proxy.

Cosa fare:

• Esporta il bundle CA della tua organizzazione e punta Claude Code ad esso con NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem
• Vedi Network configuration per le istruzioni di configurazione complete
• Non impostare NODE_TLS_REJECT_UNAUTHORIZED=0, che disabilita completamente la convalida del certificato

Host not allowed in a cloud session

Una richiesta HTTP in uscita da una sessione cloud o routine è stata bloccata dalla politica di rete dell'ambiente.

HTTP 403
x-deny-reason: host_not_allowed

Potresti anche vedere un certificato TLS che non corrisponde al certificato reale della destinazione. Le sessioni cloud instradano il traffico in uscita attraverso un proxy che applica la politica di rete, quindi un certificato non corrispondente significa che il proxy ha terminato la connessione, non la destinazione.

Questo non è un problema di rete lato client. Le sessioni cloud e routines vengono eseguite all'interno di una VM sandbox la cui rete di traffico in uscita attraverso la rete della sessione è filtrata alla allowlist dell'ambiente cloud; le operazioni GitHub e il traffico del connettore MCP utilizzano canali separati, motivo per cui possono continuare a funzionare mentre altri host sono bloccati. L'ambiente Default utilizza accesso Trusted, che consente la allowlist predefinita di registri di pacchetti, API di provider cloud, registri di container, e domini di sviluppo comuni e blocca altri domini su quel percorso.

Cosa fare:

Questi passaggi cambiano uno dei tuoi ambienti. Un organization-shared environment si apre in sola lettura nel selettore, quindi chiedi a un Owner di cambiare il suo accesso di rete dalla pagina Cloud environments in admin settings.

• Apri il tuo ambiente per la modifica, o dalla routine's form o dal environment selector dove avvii sessioni cloud.
• Nella finestra di dialogo Edit cloud environment, cambia Network access da Trusted a Custom, quindi aggiungi il dominio bloccato a Allowed domains. Inserisci un dominio per riga. Seleziona Also include default list of common package managers per mantenere la allowlist predefinita insieme ai tuoi domini personalizzati. Seleziona Full invece se desideri accesso senza restrizioni.
• Fai clic su Save changes. La prossima esecuzione utilizza l'allowlist aggiornata. Per una sessione cloud che è già aperta, vedi quando una modifica dell'accesso di rete raggiunge le sessioni esistenti.

Vedi Network access per i livelli di accesso e l'allowlist predefinita. Le sessioni CLI locali non sono interessate da questa politica.

The proxy refused the connection

Vedi questo messaggio quando Claude legge un artifact attraverso il proxy che hai impostato in HTTPS_PROXY o una proxy variable correlata. Il contenuto dell'artifact proviene da *.frame.claudeusercontent.com, quindi Claude Code invia prima al proxy una richiesta CONNECT chiedendogli di aprire un tunnel a quell'host. Quando il proxy rifiuta, nulla raggiunge l'host, e il messaggio porta lo stato HTTP del proxy:

artifact content fetch failed (proxy refused the connection: HTTP 407)
artifact content fetch failed (proxy refused the connection: HTTP 403)
the proxy refused the connection to the artifact's content host (HTTP 502)

Lo stato è la risposta del proxy al CONNECT. L'host non ha mai risposto, quindi ogni stato punta a una correzione diversa:

• HTTP 407: il proxy richiede credenziali che non ha ricevuto. Mettile nell'URL del proxy, come mostra Basic authentication.
• HTTP 403: il proxy rifiuta di fare tunnel a *.frame.claudeusercontent.com. Chiedi a chiunque gestisca il proxy di consentire quell'host, che Network access requirements elenca.
• Qualsiasi altro stato, come HTTP 502: il proxy non ha aperto il tunnel per suo motivo, come il mancato raggiungimento dell'host. Cerca lo stato nei log del proxy.
• unreadable reply al posto di uno stato: qualunque cosa sia all'indirizzo del proxy non ha risposto con una riga di stato HTTP. Controlla che l'indirizzo sia un proxy HTTP.

Cosa fare:

• Controlla l'indirizzo e le credenziali nella variabile proxy, come descrive Proxy configuration, quindi esegui curl -x http://proxy.example.com:8080 -I https://api.anthropic.com dalla shell in cui avvii Claude Code, usando il tuo URL proxy. Su Windows PowerShell, esegui curl.exe. Se questa sonda fallisce allo stesso modo, correggi prima la configurazione del proxy. Se ha successo, il rifiuto è specifico dell'host dell'artifact.
• Se la tua rete consente a Claude Code di raggiungere l'host dell'artifact direttamente, aggiungi .frame.claudeusercontent.com a NO_PROXY. Mantieni la voce stretta: una voce .claudeusercontent.com più ampia bypassa anche il proxy per bridge.claudeusercontent.com, che le organizzazioni con IP allowlisting devono mantenere sul proxy.

Prima della v2.1.238, Claude Code segnalava un tunnel rifiutato come un errore di rete generico.

The cloud environments service returned an empty or unexpected response

Claude Code richiede il tuo elenco di cloud environments in diversi punti, come quando crei una sessione cloud dalla CLI o esegui /remote-env. Quando non riesce a leggere la risposta del server, mostra uno di questi messaggi:

The cloud environments service returned an empty response (HTTP 200 with no body). This is usually temporary — try again in a moment.
The cloud environments service returned a response in an unexpected format (HTTP 200 with a non-JSON body). This is usually temporary — try again in a moment.
The cloud environments service returned a response in an unexpected format (HTTP 200 without a usable environments list). This is usually temporary — try again in a moment.

Il server ha accettato la richiesta ma ha risposto con un corpo che non è l'elenco degli ambienti: vuoto, non JSON, o JSON senza l'elenco. Questo di solito accompagna un'interruzione lato servizio e si risolve da solo. A seconda della superficie che ha richiesto l'elenco, Claude Code può aggiungere un prefisso, come couldn't list environments: nella finestra di dialogo /remote-env.

Cosa fare:

• Ritenta l'azione. Claude Code richiede di nuovo l'elenco ogni volta
• Se il messaggio continua ad apparire, controlla status.claude.com per gli incidenti attivi

Prima della v2.1.236, Claude Code mostrava un TypeError JavaScript grezzo invece di questi messaggi.

Couldn't reconnect to your Remote Control session

Couldn't reconnect to your Remote Control session. Retry, or start a fresh session without --resume.

La ripresa con claude --resume o claude --continue si riconnette alla sessione Remote Control registrata in quella conversazione. Questo messaggio significa che la riconnessione è fallita per un motivo che potrebbe essere temporaneo, come un'interruzione di rete o un errore del server, quindi Claude Code non può confermare se la sessione remota esiste ancora. La tua sessione locale continua a funzionare senza Remote Control.

Cosa fare:

• Esegui /remote-control per ritentare la connessione
• Avvia una nuova sessione con claude --remote-control per creare una nuova sessione Remote Control
• Per altri messaggi di avvio di Remote Control, vedi Troubleshoot Remote Control

Se il server segnala invece che la sessione precedente è scomparsa, non vedi questo messaggio. Claude Code avvia una nuova sessione al suo posto o mostra Previous session is unavailable — run /remote-control to start a new one.

Sessions ended while this machine was offline

Claude Code mostra questo messaggio nel terminale che esegue claude remote-control dopo che la tua macchina è stata offline abbastanza a lungo che il server ha pulito l'ambiente Remote Control che la tua macchina stava servendo. Le sessioni in quell'ambiente sono terminate e non puoi riprendere. Il conteggio è il numero di sessioni che sono terminate.

2 sessions ended while this machine was offline — the environment was cleaned up on the server and can't be resumed.

Cosa fare:

• Quando Claude Code elenca i worktrees mantenuti sotto questo messaggio, raccogli qualsiasi lavoro non committato da loro
• Esegui claude remote-control per avviare un ambiente nuovo

Couldn't share the transcript

Dopo che accetti di condividere la trascrizione della tua sessione da un prompt di sondaggio, come il session quality survey, Claude Code la carica su Anthropic, o salva un archivio locale invece su provider di terze parti, su sessioni Claude apps gateway, e quando nessuna credenziale Anthropic è disponibile. Questo messaggio significa che la condivisione non è stata completata.

Couldn't share the transcript.

Il caricamento deve rientrare in un limite di 8 MiB. Su una sessione lunga, Claude Code progressivamente elimina parti della condivisione, le impostazioni del modello dell'ultima richiesta per prime, quindi la conversazione strutturata e le trascrizioni dei subagent, e mostra questo messaggio solo quando nessuna versione ridotta può essere inviata o un errore di rete o server interrompe il caricamento. Quando Claude Code salva un archivio locale invece, il messaggio significa che non poteva scrivere l'archivio.

Cosa fare:

• Esegui /feedback per inviare la trascrizione con una descrizione di ciò che è accaduto. Vedi Report an error se /feedback non è disponibile nel tuo ambiente
• Se anche altre richieste stanno fallendo, controlla la tua connessione di rete e vedi Unable to connect to API

Couldn't send feedback

Hai inviato un rapporto dalla finestra di dialogo /feedback, /bug, o /share e il caricamento su Anthropic è fallito. La finestra di dialogo mantiene il tuo testo in modo che tu possa ritentare.

Couldn't send feedback (couldn't reach the service). If it keeps failing, you can file at https://github.com/anthropics/claude-code/issues instead.

Il testo dopo il prefisso nomina ciò che è fallito:

• : not signed in. Run /login, then retry.: la finestra di dialogo carica solo quando Claude Code ha trovato credenziali Anthropic mentre si apriva, e nessuna era utilizzabile al momento dell'invio. Ad esempio, hai effettuato il logout su questa macchina nel frattempo, o il tuo login non poteva più essere aggiornato.
• Una parentesi: (server returned <status>) è il codice di risposta del servizio; (request timed out) e (couldn't reach the service) sono guasti di rete. Quando Claude Code non riesce a nominare un motivo, la parentesi è assente.

Nella feedback drafts queue, lo stesso guasto termina con The draft is still queued. Try again later. invece, e la bozza rimane nella coda per un altro tentativo.

Cosa fare:

• Per la dicitura non-signed-in, esegui /login e invia di nuovo
• Altrimenti, invia di nuovo; se anche altre richieste stanno fallendo, controlla la tua connessione di rete e vedi Unable to connect to API
• Se continua a fallire, archivia il rapporto su github.com/anthropics/claude-code/issues, come dice il messaggio

Prima della v2.1.281, ogni invio falliva con questo messaggio una volta che un Remote Control Stop o un messaggio urgente tra sessioni era arrivato mentre la finestra di dialogo era aperta. Su quelle versioni, chiudi la finestra di dialogo, riaprila e invia di nuovo.

Errori di richiesta

Questi errori riguardano il contenuto della tua richiesta. La maggior parte proviene dall'API dopo che ha rifiutato la richiesta; alcuni sono prodotti localmente da Claude Code prima che venga inviata qualsiasi richiesta.

Prompt è troppo lungo

La conversazione più i file allegati superano la finestra di contesto del modello.

Prompt is too long

In una sessione interattiva, Claude Code mostra questo errore come:

Context limit reached · /compact or /clear to continue

La riga nomina solo /clear quando DISABLE_COMPACT è impostato. Le forme più lunghe dell'errore, come la forma di compattazione non riuscita di seguito, mantengono la dicitura Prompt is too long ·. Nell'output -p e nella trascrizione, il testo rimane Prompt is too long.

Quando hai disattivato la compattazione automatica nelle tue impostazioni utente, la riga dice anche:

Context limit reached · /compact or /clear to continue · auto-compact is off · /config to turn it on

L'interruttore Auto-compact in /config scrive autoCompactEnabled nelle impostazioni utente. L'hint appare solo quando una modifica /config avrebbe effetto. Ad esempio, non appare quando DISABLE_AUTO_COMPACT o DISABLE_COMPACT ha disattivato la compattazione automatica. Non appare nemmeno quando un ambito di precedenza superiore, come le impostazioni di progetto o gestite, ha impostato autoCompactEnabled su false. Prima della v2.1.235, la riga non conteneva alcun hint di compattazione automatica.

Amazon Bedrock segnala questa condizione come Input is too long for requested model., che Claude Code gestisce allo stesso modo. Prima della v2.1.217, Claude Code non riconosceva la dicitura di Bedrock, quindi la compattazione automatica non si attivava mai e /compact falliva con lo stesso errore.

Un gateway di app Claude segnala questa condizione come capability_rejected: prompt_too_long quando un upstream cloud rifiuta la richiesta nella forma di errore propria del provider. Claude Code tratta il token come Prompt is too long. Prima della v2.1.228, Claude Code non riconosceva il token, quindi la compattazione automatica non si attivava.

Quando la compattazione automatica è stata eseguita su questo turno e ha fallito su un errore sottostante, come un modello non disponibile o un errore di autenticazione, il messaggio nomina quell'errore dopo un separatore:

Prompt is too long · automatic compaction failed: <the underlying error>

Risolvi prima l'errore nominato; /compact fallisce sullo stesso errore finché non lo fai. Prima della v2.1.229, una compattazione automatica non riuscita mostrava Prompt is too long senza la causa.

Quando la compattazione automatica viene eseguita su questo errore, normalmente riassume i tuoi scambi più vecchi e mantiene i più recenti. Come ultima risorsa, Claude Code riassume diversamente:

• Quando non può riassumere alcuno scambio completo, Claude Code mantiene il tuo prompt più recente parola per parola e riassume tutto prima di esso.
• In quel caso, quando la conversazione non termina con il tuo prompt, Claude Code riassume l'intera conversazione.

Claude Code salta questo recupero quando il contenuto che porterebbe avanti non contiene alcuna risposta del modello e meno di circa 1.000 token del tuo testo, come un breve tentativo inviato dopo un incolla di dimensioni eccessive. Esegui /clear per ricominciare da capo. Prima della v2.1.269, la compattazione falliva ogni volta che non poteva riassumere uno scambio completo, quindi una sessione in quello stato colpiva questo errore di nuovo ad ogni turno.

Una conversazione con un singolo scambio non ha turni precedenti da riassumere. Quando la compattazione automatica avrebbe dovuto essere eseguita su uno, Claude Code salta il tentativo e spiega cosa riempie la richiesta. Quando l'API non segnala i conteggi dei token nel suo errore, il messaggio recita:

Prompt is too long · this conversation is a single exchange and cannot be compacted — the request size comes mostly from system prompt, tool definitions, or attachments.

Quando l'API segnala i conteggi dei token nel suo errore, Claude Code li confronta con la sua stima della dimensione della conversazione per dire quale è la maggior parte della richiesta: il contenuto della conversazione stessa, o il prompt di sistema, le definizioni degli strumenti e il contenuto degli allegati che Claude Code invia con essa. Quando il contenuto della conversazione è la maggior parte della richiesta, il messaggio recita:

Prompt is too long · the request is ~<request tokens> tokens (limit <limit>) and this conversation's own content is most of it. A single-exchange conversation cannot be compacted; start with less content (smaller files or pasted text).

Quando la maggior parte della richiesta è al di fuori della conversazione, il messaggio recita:

Prompt is too long · the request is ~<request tokens> tokens (limit <limit>) but this conversation is only ~<conversation tokens> tokens — the rest is system prompt, tool definitions, and attachment content. A single-exchange conversation cannot be compacted; reduce attached files/tools or start with less context.

Prima della v2.1.162, Claude Code tentava comunque la compattazione e mostrava il semplice Prompt is too long quando falliva.

Cosa fare:

• Esegui /compact per riassumere i turni precedenti e liberare spazio, oppure /clear per ricominciare da capo. Se /compact risponde Not enough messages to compact., la conversazione è un singolo scambio senza nulla di precedente da riassumere, quindi lo spazio è occupato da quel prompt e da quello che Claude Code invia con ogni richiesta: esegui /clear e reinvia con meno testo incollato o allegati più piccoli, oppure riduci le definizioni degli strumenti e i file di memoria utilizzando i passaggi seguenti
• Esegui /context per vedere una suddivisione di ciò che consuma la finestra: prompt di sistema, strumenti, file di memoria e messaggi
• Disabilita i server MCP che non stai utilizzando con /mcp disable <name> per rimuovere le loro definizioni di strumenti dal contesto
• Taglia i file di memoria CLAUDE.md di grandi dimensioni, oppure sposta le istruzioni in regole con ambito di percorso che si caricano solo quando rilevanti
• La compattazione automatica è attiva per impostazione predefinita e normalmente previene questo errore. Se l'hai disattivata in /config o con DISABLE_AUTO_COMPACT, riattivala. Se la mantieni disattivata, esegui /compact tu stesso prima che la finestra si riempia.

Vedi Esplora la finestra di contesto per una visualizzazione interattiva di come il contesto si riempie.

Il contesto supera il limite di token

/context mostra questo avviso in cima al suo output quando la conversazione ha superato la finestra di contesto del modello. Le richieste falliscono con Prompt is too long finché non liberi spazio. Una sessione interattiva mostra quell'errore come la riga Context limit reached.

Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.

Quando il limite che hai superato è una finestra di compattazione, come il limite di 200K sui modelli con contesto 1M, l'avviso recita diversamente. Una finestra di compattazione può stare al di sotto della finestra di contesto del modello, quindi le richieste oltre ad essa possono ancora avere successo.

Context is 94k tokens past the 200k-token compaction window — run /compact to reduce usage.

Entrambe le forme nominano /clear invece di /compact quando hai impostato DISABLE_COMPACT.

Cosa fare:

• In una conversazione multi-turno, esegui /compact per riassumere i turni precedenti e liberare spazio. Per ricominciare da capo, esegui /clear
• Per altri modi per ridurre l'utilizzo, vedi Prompt è troppo lungo

Prima della v2.1.216, /context mostrava l'utilizzo sopra il 100% senza una riga di avviso che spiegasse cosa significava o come recuperare.

Richiesta troppo grande

Il corpo della richiesta grezza ha superato il limite di 32MB dell'API prima della tokenizzazione, solitamente a causa di contenuto incollato di grandi dimensioni, risultati degli strumenti o allegati. Questo limite è separato dalla finestra di contesto.

Request too large (max 32MB). Accumulated images and attachments in the conversation pushed the request over the limit. Run /compact, or double press esc to go back and remove attachments.

Quando la richiesta è andata direttamente all'API Claude e l'API stessa l'ha rifiutata, Claude Code misura la conversazione e formula il messaggio in base al fatto che il recupero possa funzionare. Attraverso un proxy, gateway o provider cloud ottieni il messaggio generale. Le forme misurate:

• Request too large (max 32MB; 20.1MB of about 33.4MB is images or documents).: le immagini o i documenti hanno spinto la richiesta oltre il limite. Claude Code ritenta con essi rimossi.
• Request too large for the API's 32MB request limit: i messaggi da soli superano il limite, quindi il messaggio dice compacting cannot make it fit e Claude Code non ritenta. In modalità non interattiva, il messaggio ti dice di ridurre l'input o avviare una nuova sessione.

Prima della v2.1.212, le conversazioni con abbastanza immagini accumulate fallivano ad ogni turno con Request too large (max 32MB). Double press esc to go back and try with a smaller file. Prima della v2.1.229, Claude Code mostrava il consiglio di allegato per ogni rifiuto, anche quando la compattazione non poteva aiutare.

Cosa fare:

• Se il messaggio dice compacting cannot make it fit, premi Esc due volte per tornare indietro oltre il turno che ha aggiunto il contenuto di grandi dimensioni, oppure esegui /clear per ricominciare da capo
• Altrimenti, esegui /compact, che elimina le immagini e gli allegati accumulati
• Fai riferimento ai file di grandi dimensioni per percorso invece di incollarne il contenuto, in modo che Claude possa leggerli in blocchi
• Per le immagini, vedi L'immagine era troppo grande di seguito

L'immagine era troppo grande

Un'immagine incollata o allegata supera i limiti di dimensione o dimensione dell'API.

Image was too large. Double press esc to go back and try again with a smaller image.
API Error: 400 ... image dimensions exceed max allowed size

Claude Code sostituisce l'immagine non elaborabile con un segnaposto di testo e ritenta, quindi i messaggi successivi hanno successo. Nelle versioni precedenti alla 2.1.142, un'immagine incollata potrebbe rimanere nella conversazione e ripetere lo stesso errore ad ogni messaggio successivo. Per recuperare su quelle versioni, premi Esc due volte e torna indietro oltre il turno in cui è stata aggiunta l'immagine.

Cosa fare:

• Ridimensiona l'immagine prima di incollarla. L'API accetta immagini fino a 8000 pixel sul lato più lungo per una singola immagine, o 2000 pixel quando molte immagini sono nel contesto.
• Fai uno screenshot più stretto della regione rilevante invece dello schermo intero

Impossibile ridimensionare l'immagine

Claude Code non ha potuto ridimensionare un'immagine allegata prima di inviarla all'API.

Unable to resize image — image processing is unavailable and dimensions could not be read from the file header. Please convert the image to PNG, JPEG, GIF, or WebP.
Unable to resize image — dimensions exceed the 2000x2000px limit and image processing failed. Please resize the image to reduce its pixel dimensions.
Unable to resize image (… raw, … base64). The image exceeds the … API limit and compression failed. Please resize the image manually or use a smaller image.
Unable to resize image — could not verify image dimensions are within the 2000x2000px API limit.
Unable to resize image — it is a CMYK JPEG, which Claude Code cannot decode, and at …px it is over the 2000x2000px limit, so it cannot be sent. Re-save it as an RGB PNG or JPEG and try again.
Unable to resize image — it is an animated WebP whose first frame Claude Code cannot decode, and at …px it is over the 2000x2000px limit, so it cannot be sent. Save its first frame as a PNG or JPEG and try again.
Unable to resize image — its pixels could not be decoded (the file may be damaged, or use an encoding Claude Code cannot read), and it is over the … API limit (… raw, … base64), so it cannot be sent. Re-save it as a PNG or JPEG and try again.

Claude Code normalmente ridimensiona automaticamente le immagini di grandi dimensioni. Questi errori significano che l'immagine non poteva essere decodificata o ridimensionata per rientrare nei limiti dell'API.

Cosa fare:

• Se il messaggio ti chiede di convertire l'immagine, convertila in PNG, JPEG, GIF o WebP e allegala di nuovo. Claude Code può verificare le dimensioni per questi formati dall'intestazione del file, senza decodificare l'immagine.
• Se il messaggio segnala un limite di dimensione o dimensione, ridimensiona o ricomprimi l'immagine al di sotto di quel limite prima di allegare.
• Se il messaggio nomina una causa, come un JPEG CMYK, un WebP animato o un file possibilmente danneggiato, risalva l'immagine nel formato che il messaggio suggerisce e allegala di nuovo.

Errori PDF

Il PDF che hai allegato non poteva essere elaborato. I messaggi sono mostrati qui nella loro forma non interattiva; in una sessione interattiva ti chiedono invece di premere Esc due volte e riprovare.

PDF too large (max 100 pages, 20MB). Try reading the file a different way (e.g., extract text with pdftotext).
PDF is password protected. Try using a CLI tool to extract or convert the PDF.
The PDF file was not valid. Try converting it to text first (e.g., pdftotext).

Cosa fare:

• Per i PDF di grandi dimensioni, chiedi a Claude di leggere un intervallo di pagine con lo strumento Read invece di allegare l'intero file, oppure estrai il testo con uno strumento come pdftotext e fai riferimento al file di output per percorso
• Per i PDF protetti o non validi, rimuovi la password o riesporta il file dall'applicazione sorgente, quindi riprova

Quando Claude legge un intervallo di pagine da un PDF con lo strumento Read, la lettura può fallire con un messaggio diverso:

pdftoppm is not installed. Install poppler-utils (e.g. `brew install poppler` or `apt-get install poppler-utils`) to enable PDF page rendering.

Le letture dell'intervallo di pagine eseguono il rendering delle pagine con pdftoppm. Installa poppler-utils con il comando che il messaggio fornisce, o su altre piattaforme una build poppler che mette pdftoppm sul tuo PATH. Vedi Comportamento dello strumento Read per quali PDF vengono letti per intervallo di pagine.

Gli input extra non sono consentiti

Un proxy o gateway LLM tra Claude Code e l'API ha rimosso l'intestazione della richiesta anthropic-beta, quindi l'API ha rifiutato i campi che dipendono da essa.

API Error: 400 ... Extra inputs are not permitted ... context_management

Claude Code invia campi solo beta come context_management insieme a un'intestazione anthropic-beta che li abilita. Quando un gateway inoltra il corpo ma elimina l'intestazione, l'API vede campi che non riconosce.

Cosa fare:

• Configura il tuo gateway per inoltrare l'intestazione anthropic-beta. Vedi feature pass-through per ciò che i gateway devono inoltrare.
• Come fallback, imposta CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 prima di avviare. Disabilita le capacità pre-release copre l'ambito esatto.

Lo schema di input dello strumento non è valido

Uno strumento nella richiesta ha dichiarato un input_schema che non supera la convalida JSON Schema dell'API, quindi l'API ha rifiutato l'intera richiesta. Il numero dopo tools. è la posizione dello strumento che fallisce nell'elenco degli strumenti della richiesta, non un nome che puoi cercare.

API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid
API Error: 400 ... tools.N.custom.input_schema.properties: Property keys should match pattern '^[a-zA-Z0-9_.-]{1,64}$'

La prima forma significa che lo schema non è un JSON Schema draft 2020-12 valido. La seconda significa che un nome di proprietà di primo livello non corrisponde al pattern che il messaggio cita.

Claude Code esclude gli strumenti MCP il cui schema di input fallirebbe questa convalida quando carica gli strumenti di un server, quindi le richieste normalmente non ne includono mai uno.

Su una distribuzione in cui il recupero dei flag è disattivato, o su una macchina i cui flag non sono mai arrivati, Claude Code registra nel log del server quale strumento verrebbe rifiutato ma lo invia comunque, quindi questo errore può ancora verificarsi.

L'errore può verificarsi anche per uno strumento il cui schema dichiara un dialetto JSON Schema diverso da draft 2020-12 in $schema. Claude Code non controlla questi schemi rispetto al meta-schema JSON Schema, anche se il controllo del nome della proprietà di primo livello si applica comunque.

Prima della v2.1.216, nessuna distribuzione eseguiva i controlli di esclusione.

Cosa fare:

• Se la tua versione di Claude Code è precedente alla v2.1.216, esegui claude update.
• Rimuovi o disabilita il server MCP che dichiara lo schema non valido. L'errore nomina lo strumento solo per posizione. Sulla v2.1.216 o successiva, controlla il log di ogni server per una riga che nomina uno strumento il cui schema di input verrebbe rifiutato. Se nessun log ne nomina uno, disabilita i server uno alla volta.
• Se mantieni il server, correggi il input_schema dello strumento. Lo schema deve essere un JSON Schema valido e i nomi delle proprietà di primo livello devono essere da 1 a 64 caratteri e utilizzare solo lettere ASCII e cifre, _, . e -. Vedi Strumenti con schemi di input non validi.

tool\_use.name oltre 200 caratteri

Una chiamata a uno strumento nella cronologia della conversazione porta un nome più lungo dei 200 caratteri che l'API accetta in una richiesta:

API Error: 400 ... tool_use.name: String should have at most 200 characters

Claude Code taglia tale nome a 200 caratteri quando la risposta arriva e quando carica una conversazione salvata, quindi la chiamata fallisce con un errore dello strumento No such tool available e la conversazione continua senza questo errore API.

Cosa fare:

• Esegui claude update, quindi riprendi la conversazione. La versione aggiornata ripara il nome eccessivamente lungo quando carica la trascrizione, quindi una conversazione che era bloccata funziona di nuovo.

Prima della v2.1.281, il nome eccessivamente lungo rimaneva nella cronologia e l'API rifiutava ogni richiesta che reinviava la conversazione, inclusi /compact e --resume, quindi questo errore si ripeteva e la conversazione era bloccata.

C'è un problema con il modello selezionato

Il nome del modello configurato non è stato riconosciuto o il tuo account non ha accesso ad esso. A partire dalla v2.1.160 l'hint finale, mostrato qui nella sua forma interattiva, varia in base alla superficie.

There's an issue with the selected model (claude-...). It may not exist or you may not have access to it. Run /model to pick a different model.

Cosa fare:

• CLI interattiva: esegui /model per scegliere dai modelli disponibili per il tuo account.
• Modalità non interattiva (-p): passa --model con un alias o ID valido, oppure imposta ANTHROPIC_MODEL. Il testo dell'errore mostra Run --model su questa superficie.
• Agent SDK: il testo dell'errore omette l'hint perché il modello è impostato a livello di programmazione. Imposta model su Options in TypeScript o ClaudeAgentOptions(model=...) in Python, e gestisci l'errore strutturato model_not_found per mostrare il tuo nuovo tentativo o selettore di modello.
• Usa un alias come sonnet o opus invece di un ID completo con versione. Gli alias si risolvono in un valore predefinito mantenuto in modo che non diventino obsoleti. Vedi Configurazione del modello.
• Se il modello sbagliato continua a tornare nella CLI, un ID obsoleto è impostato da qualche parte. Controlla i posti in cui puoi impostare un modello in ordine di priorità e rimuovi il valore obsoleto.
• Claude Code segnala un accesso claude.ai scaduto come Login scaduto, non come questo errore. Prima della v2.1.206, un accesso scaduto che non poteva più essere aggiornato falliva con ogni modello con questo errore; esegui /login se lo vedi su una versione precedente.
• Per le distribuzioni di Google Cloud's Agent Platform, vedi Risoluzione dei problemi di Google Cloud's Agent Platform.

Il modello non è un ID modello riconosciuto

La stringa che hai passato a un cambio di modello non è una che Claude Code può usare come modello, quindi ha rifiutato il cambio senza inviare una richiesta e la sessione mantiene il suo modello attuale. Puoi ottenere questo errore quando un modello è impostato tramite il metodo Agent SDK setModel(), da un'app che esegue la CLI di Claude Code per te, come l'app Desktop, o quando scegli un modello da un dispositivo connesso tramite Remote Control. Prima della v2.1.200, Claude Code salvava la stringa e falliva alla richiesta successiva con C'è un problema con il modello selezionato.

Model "Sonnet5" is not a recognized model id. Did you mean 'claude-sonnet-5'?

In questo esempio un'app ha inviato il nome visualizzato Sonnet 5, che il messaggio ripete senza il suo spazio. L'hint finale nomina l'alias o l'ID del modello più vicino. Quando nulla è abbastanza vicino, recita invece Run /model to see available models. In una sessione che l'app Desktop avvia per te, l'hint senza corrispondenza recita Switch to a different model.

Quando cambi tramite l'Agent SDK o un'app sull'API Anthropic, solo una stringa che non può essere un ID modello ottiene questo errore, come un nome visualizzato o una stringa vuota.

Quando scegli un modello da un dispositivo Remote Control, Claude Code controlla la stringa localmente. Qualsiasi stringa che non sia un alias di modello, un modello che Claude Code elenca o che hai configurato, o un ID che inizia con claude- ottiene questo errore, un ID digitato male come claud-sonnet-5 incluso. Prima della v2.1.260, questo controllo non copriva le scelte di Remote Control, quindi una stringa non riconosciuta veniva applicata e falliva alla richiesta successiva.

Cosa fare:

• Esegui /model senza argomenti per aprire il selettore e scegliere dai modelli disponibili per il tuo account, quindi passa l'alias o l'ID mostrato lì
• Se hai usato un alias che solo una versione più recente di Claude Code supporta, esegui claude update, oppure passa l'ID completo del modello. Il server può comunque richiedere una versione minima di Claude Code per quel modello; vedi Claude Code non supporta questo modello.
• Un modello salvato prima della v2.1.200 non viene riparato da questo controllo. Se un valore obsoleto continua a tornare, rimuovilo dalle posizioni elencate in Impostazione del modello.
• Su qualsiasi provider diverso dall'API Anthropic, o dietro un gateway o ANTHROPIC_BASE_URL personalizzato, solo una stringa vuota ottiene questo errore. Claude Code può comunque scrivere la riga diagnostica del modello non riconosciuto al momento della richiesta, su ogni provider.

Modello non trovato

Hai cambiato a un modello per nome e Claude Code non ha potuto confermare che esista un modello con quel nome. Quando il nome non è un alias di modello o un'altra ortografia che Claude Code accetta localmente, Claude Code lo verifica con una richiesta API minima, e questo errore è solitamente la risposta del tuo endpoint API. Con /model <name>, un nome che non può essere un ID modello affatto, come uno contenente spazi, ottiene lo stesso messaggio.

Model 'claude-opus-9' not found

Su provider con ID modello specifici del provider, il messaggio può aggiungere un suggerimento Try '...' instead che nomina l'ID del tuo provider per un modello di fallback.

Cosa fare:

• Esegui /model senza argomenti e scegli dai modelli disponibili per il tuo account, oppure usa un alias di modello come sonnet, che si risolve in un valore predefinito mantenuto
• Se hai digitato un ID completo, controllalo rispetto al catalogo dei modelli del tuo provider. Un modello appena lanciato può essere disponibile sull'API Anthropic prima che il tuo provider o la tua regione lo offra.
• Nell'Agent SDK, setModel() fallisce con questo messaggio e la sessione continua a funzionare sul suo modello precedente. Nell'SDK TypeScript, chiama supportedModels() per elencare i modelli a cui puoi passare.
• Prima della v2.1.265, /model ha anche rifiutato l'ortografia dell'alias opusplan[1m] con questo errore. Su quelle versioni, aggiorna Claude Code, oppure imposta il modello in impostazioni o con --model invece.

Impossibile confermare il modello con l'API

Hai cambiato modelli tramite il metodo Agent SDK setModel() o un'app che esegue la CLI di Claude Code per te, come l'app Desktop, e la richiesta che conferma l'ID del modello con il tuo endpoint API non ha ricevuto risposta entro cinque secondi. La sessione mantiene il suo modello attuale.

Couldn't confirm model "claude-sonnet-5" with the API. Try again, or run /model to see available models.

In una sessione che l'app Desktop avvia per te, il messaggio termina a Try again.

Cosa fare:

• Cambia di nuovo al modello
• Se il cambio continua a fallire, controlla che Claude Code possa raggiungere il tuo endpoint API; vedi Errori di rete e connessione

Errore API durante il controllo del modello selezionato

Hai selezionato un modello con /model <name>, oppure un'app connessa alla sessione ha richiesto il cambio. L'API ha rifiutato la richiesta minima che Claude Code invia per verificare il modello, per un motivo che non ha una voce propria, come un rate limit o un errore del server. La sessione mantiene il suo modello attuale, e il messaggio termina dicendo così:

API error: 429 <the server's explanation> · model not changed

Il mezzo del messaggio è lo stato HTTP e la spiegazione propria del server.

Cosa fare:

• Agisci sulla spiegazione del server; per un rate limit o uno stato 5xx, attendi e seleziona di nuovo il modello
• I rifiuti con la loro propria dicitura sono coperti dalle voci circostanti, come Modello non trovato e Il modello è limitato dalle impostazioni della tua organizzazione

Claude Opus non è disponibile con il piano Claude Pro

Il tuo piano di abbonamento attivo non include il modello che hai selezionato.

Claude Opus is not available with the Claude Pro plan. If you have updated your subscription plan recently, run /logout and /login for the plan to take effect.

In una sessione che l'app Claude Desktop esegue, il messaggio dice di sign out and sign in again invece di nominare i comandi.

Cosa fare:

• Esegui /model e seleziona un modello che il tuo piano include
• Se hai aggiornato il tuo piano di recente e vedi ancora questo, esegui /logout quindi /login. Il token memorizzato riflette il tuo piano al momento dell'accesso, quindi l'aggiornamento su claude.ai non ha effetto in una sessione esistente finché non ti autentichi di nuovo.
• Vedi claude.com/pricing per quali modelli ogni piano include

Claude Code non supporta questo modello

L'API ha rifiutato la richiesta con un 400 perché la tua versione di Claude Code è al di sotto di un minimo richiesto. O il modello che hai selezionato richiede una versione più recente, che il server controlla per modello, o la politica della tua organizzazione ne richiede una. Il 400 porta il codice di errore claude_code_version_too_old, e il messaggio dice quale minimo si applica.

API Error: 400 Claude Code 2.1.219 does not support this model; version 2.1.255 or newer is required. Run 'claude update', or update the Claude desktop app, then try again.

La dicitura della politica organizzativa recita:

API Error: 400 Claude Code 2.1.240 is older than the minimum version required by your organization's policy. Run 'claude update', or update the Claude desktop app, to continue.

La versione che l'API controlla è quella segnalata dal binario di Claude Code che ha effettuato la richiesta.

Cosa fare:

Aggiorna quel binario, quindi avvia una nuova sessione. Da dove proviene il binario decide come, tranne in un ambiente auto-ospitato:

• Per la dicitura per modello, puoi continuare a lavorare nella sessione attuale passando a un altro modello: esegui /model nella CLI, chiama setModel() sull'oggetto Query dell'SDK TypeScript in modalità di input in streaming, o chiama set_model() su ClaudeSDKClient dell'SDK Python
• Per la dicitura della politica organizzativa, aggiorna prima di continuare

Il modello è limitato dalle impostazioni della tua organizzazione

L'amministratore della tua organizzazione ha disabilitato questo modello nella console di amministrazione claude.ai, oppure le impostazioni gestite lo escludono tramite un'allowlist availableModels o un elenco deniedModels. L'avviso appare all'avvio quando --model, ANTHROPIC_MODEL, o l'impostazione model ha nominato il modello limitato, e nomina il modello che la sessione usa invece. Se le impostazioni gestite non lasciano alcun modello consentito per la sessione da usare, vedi Le impostazioni gestite bloccano il modello predefinito. L'avviso di sostituzione può anche apparire a metà sessione dopo che un amministratore disabilita il modello su cui una sessione è in esecuzione nella console di amministrazione claude.ai.

Model "claude-opus-4-8" is restricted by your organization's settings. Using claude-sonnet-4-6 instead.

Digitare /model <name> per un modello limitato viene rifiutato e la sessione mantiene il suo modello attuale. Per un modello disabilitato nella console di amministrazione, il rifiuto recita Model '<name>' is restricted by your organization's settings. Run /model to choose a different model. Per un modello che le impostazioni gestite escludono, recita Model '<name>' is not available. Your organization restricts model selection.

Un avviso con prefisso il nome di un agente, di una skill o di un comando significa che la restrizione si è applicata al modello richiesto di quel subagent: il subagent viene eseguito sul modello sostituito e il modello della tua sessione rimane invariato. Prima della v2.1.223, Claude Code mostrava l'avviso solo per i subagent lanciati con lo strumento Agent.

Claude Code tratta un alias di famiglia di modelli, uno di opus, sonnet, haiku, o fable, come una richiesta per quella famiglia piuttosto che per la sua versione più recente. Sull'API Anthropic e su Claude Platform on AWS, un alias di famiglia limitato si risolve nella versione più recente della famiglia che le impostazioni della tua organizzazione consentono, e l'avviso di sostituzione nomina quella versione. Claude Code rifiuta /model <alias> solo quando ogni versione della famiglia è limitata. Prima della v2.1.205, un alias di famiglia veniva sostituito o rifiutato in base alla sua versione più recente sola, anche quando una versione precedente della stessa famiglia era consentita.

Cosa fare:

• Esegui /model per scegliere dai modelli che la tua organizzazione consente. I modelli limitati sono nascosti dal selettore.
• Se il modello limitato è stato impostato in --model, ANTHROPIC_MODEL, il campo model di un file di impostazioni, o il frontmatter model di un subagent, di una skill o di un comando, rimuovi o aggiorna quel valore in modo che l'avviso non si ripeta
• Se hai bisogno di accesso al modello limitato, chiedi all'amministratore della tua organizzazione di abilitarlo. Vedi Restrizioni del modello dell'organizzazione.

Impossibile passare al modello predefinito

Hai selezionato il modello Predefinito, ad esempio selezionando la riga Predefinito nel selettore /model o digitando /model default. Claude Code ha rifiutato il cambio, quindi la sessione mantiene il suo modello attuale.

Can't switch to the default model: your organization's managed settings block it (claude-opus-4-6) in "deniedModels", and none of the models they allow can be used as the default instead. Ask your administrator to update "deniedModels" or "availableModels".

La dicitura dopo i due punti nomina ciò che ha bloccato il cambio:

• your organization's managed settings block it ... in "deniedModels": un elenco di negazione gestito blocca il modello a cui l'opzione Predefinito si risolve
• your organization allows only the models listed in "availableModels": un'allowlist availableModels gestita con availableModelsMatch impostato su "exact" lascia fuori il modello a cui l'opzione Predefinito si risolve
• Claude Code couldn't read your organization's managed settings to check which models they allow: le impostazioni gestite non potevano essere lette, e Claude Code rifiuta il cambio piuttosto che applicarlo senza controllo

Cosa fare:

• Per le diciture deniedModels e availableModels, esegui /model e seleziona un modello che la tua organizzazione consente per nome
• Chiedi al tuo amministratore di aggiornare l'impostazione gestita che il messaggio nomina
• Per la dicitura couldn't read, riavvia Claude Code; se continua a succedere, chiedi al tuo amministratore di controllare le impostazioni gestite

Se una sessione invece non riesce ad avviarsi con un messaggio Claude Code can't start in queste impostazioni gestite, vedi Le impostazioni gestite bloccano il modello predefinito.

Il cambio di modello è stato bloccato da un hook PreModelSwitch

Un hook PreModelSwitch non ha approvato il cambio di modello che tu o un client hai richiesto, quindi la sessione mantiene il suo modello attuale. Quando il cambio è venuto da un host Agent SDK o Remote Control piuttosto che da un comando che hai digitato, il messaggio recita Model switch blocked by a PreModelSwitch hook senza nominare il modello di destinazione.

Model switch to Opus 4.6 was blocked by a PreModelSwitch hook: Opus 4.6 is retired for this project. Use a newer model.

La ragione dopo i due punti dice cosa ha rifiutato il cambio:

• Una ragione che un hook ha scritto: un hook PreModelSwitch ha fornito quella ragione quando ha negato il cambio o chiesto conferma. Affronta ciò che chiede, o seleziona un modello che i tuoi hook consentono.
• PreModelSwitch hook <name> did not respond before its timeout: un hook che non risponde prima del suo timeout blocca il cambio. Correggi il comando sospeso o aumenta il timeout di quell'hook, quindi cambia di nuovo.
• confirmation required, and this session cannot ask: un hook ha risposto ask senza una ragione, e una richiesta di controllo non ha modo di mostrare la richiesta di conferma. Un comando /model in un'esecuzione -p segnala la stessa condizione con (run /model interactively to confirm) dopo la ragione. Effettua il cambio da una sessione interattiva, o cambia la decisione dell'hook per questo modello.
• so organization-managed PreModelSwitch hooks could not be checked: Claude Code non ha potuto dire quali hook PreModelSwitch i plugin gestiti della tua organizzazione forniscono, ad esempio perché un plugin gestito non è riuscito a caricarsi. Uno di quegli hook potrebbe bloccare il cambio, quindi Claude Code rifiuta piuttosto che applicare il cambio senza controllo. L'inizio della ragione nomina cosa ha fallito. Claude Code ricontrolla ad ogni tentativo di cambio, quindi un fallimento che da allora si è chiarito smette di bloccare; se continua a fallire, esegui claude --debug e cambia di nuovo per catturare i dettagli, quindi correggi il plugin o chiedi al tuo amministratore di correggerlo.
• a PreModelSwitch hook failed before answering o PreModelSwitch hooks were cancelled (the control stream closed) before answering: l'esecuzione dell'hook è terminata senza un verdetto, e Claude Code non lo tratta come approvazione. Esegui claude --debug per vedere cosa ha fallito, quindi cambia di nuovo.

Prima della v2.1.260, il rifiuto del plugin gestito recitava plugin hooks could not be loaded, so PreModelSwitch hooks could not be checked; see the debug log. Claude Code ha ritentato il caricamento del plugin una volta e poi ha rifiutato i cambi successivi nella sessione, anche quando la tua organizzazione non ha gestito alcun plugin. Riavvia la sessione per eseguire di nuovo il caricamento del plugin su quelle versioni.

Impossibile salvarlo come predefinito

Hai selezionato un modello da salvare come predefinito, ad esempio con /model <name> o Enter nel selettore /model, e Claude Code non ha potuto scrivere la selezione nel file delle impostazioni utente, ~/.claude/settings.json. Il cambio stesso è stato applicato, quindi la sessione attuale viene eseguita sul modello che hai selezionato, ma il tuo predefinito rimane invariato e la sessione successiva inizia sul valore precedente.

Set model to Fable 5.1 for this session only · couldn't save it as your default: ~/.claude/settings.json can't be written (EROFS)

La ragione dopo il percorso del file dice cosa ha fallito:

• can't be written (<code>): la scrittura ha fallito con il codice di errore del sistema operativo tra parentesi, come EROFS quando il file, o il file a cui si collega, si trova su un filesystem che rifiuta le scritture. Rendi il file scrivibile e cambia di nuovo. Se un altro strumento genera il file, imposta la chiave model in quello strumento; vedi Una modifica che hai fatto in Claude Code viene persa nelle nuove sessioni.
• isn't valid JSON: il file su disco non si analizza, e Claude Code lo lascia intatto piuttosto che sovrascrivere il contenuto che non può leggere di nuovo. Correggi l'errore di sintassi, quindi cambia di nuovo; vedi Correggi un file di impostazioni rotto.

Un avviso che termina couldn't confirm it was saved as your default (~/.claude/settings.json is still being written) significa che la scrittura non era terminata dopo tre secondi. Continua in background, quindi il predefinito potrebbe comunque essere salvato; controlla quale modello la tua sessione successiva inizia, oppure esegui /model <name> di nuovo.

Prima della v2.1.265, l'avviso diceva che il modello era saved as your default for new sessions anche quando la scrittura ha fallito.

L'advisor è meno capace del modello principale attuale

Il tuo modello advisor si colloca al di sotto del modello principale della tua sessione, quindi Claude Code mantiene la selezione ma non collega l'advisor alle richieste del modello principale.

Advisor set to Opus 4.8
Note: Opus 4.8 is less capable than the current main model (Sonnet 5.5), so the advisor will not activate. Choose a more capable advisor, or switch to a smaller main model.

Altri messaggi segnalano la stessa condizione:

• In una sessione interattiva, una notifica recita Advisor will not activate on the main model (advisor is less capable); subagents may still use it and may use more tokens · /advisor.
• All'avvio con il flag --advisor, un avviso recita "<advisor>" cannot advise "<main model>" (the advisor must be at least as capable as the main model). The advisor will not be used for the main model. e la sessione si avvia comunque.

Cosa fare:

• Scegli un advisor di rango più alto o un modello principale di rango più basso. Scegli un modello advisor mostra la classifica ed elenca gli advisor accettati per ogni modello principale.
• Lascia impostato l'advisor se vuoi che i subagent il cui modello può assistere continuino a usarlo

Prima della v2.1.287, Claude Code classificava diversamente diverse combinazioni. Mostrava questa nota per un advisor Sonnet 5.5 con un modello principale Opus 4.7 o Opus 4.8, una combinazione che ora accetta. Collegava anche alcuni advisor che ora producono questa nota, come un advisor Opus 4.8 con un modello principale Sonnet 5.5.

thinking.type.enabled non è supportato per questo modello

La tua versione di Claude Code è più vecchia del minimo per il modello selezionato. La CLI ha inviato una configurazione di ragionamento che il modello non accetta più.

API Error: 400 ... "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

Cosa fare:

• Esegui claude update e riavvia Claude Code. Opus 4.7 ha bisogno della v2.1.111 o successiva. Opus 4.8 ha bisogno della v2.1.154 o successiva. Sonnet 5 ha bisogno della v2.1.197 o successiva. Opus 5 ha bisogno della v2.1.219 o successiva. Opus 5.5 ha bisogno della v2.1.280 o successiva. Sonnet 5.5 ha bisogno della v2.1.284 o successiva
• Se non puoi aggiornare, esegui /model e seleziona Opus 4.6 o Sonnet 4.6
• Se colpisci questo nell'Agent SDK, aggiorna il pacchetto SDK. Opus 4.8 ha bisogno di TypeScript SDK v0.3.154 o successiva e Python SDK v0.2.88 o successiva. Sonnet 5 ha bisogno di TypeScript SDK v0.3.197 o successiva. Opus 5 ha bisogno di TypeScript SDK v0.3.219 o successiva. Opus 5.5 ha bisogno di TypeScript SDK v0.3.280 o successiva. Sonnet 5.5 ha bisogno di TypeScript SDK v0.3.284 o successiva

Lo sforzo non è disponibile con il ragionamento disattivato

Hai disattivato il ragionamento esteso e hai eseguito a un livello di sforzo superiore a high. Il modello non accetta quella combinazione, quindi l'API ha rifiutato la richiesta.

API Error: Effort 'xhigh' isn't available with thinking turned off on this model · run /effort high to continue, or turn thinking back on (unset MAX_THINKING_TOKENS=0)

L'hint dopo il · varia in base alla sessione: in una sessione non interattiva recita use --effort high (or the effortLevel setting), e in una sessione che l'app Claude Desktop esegue recita you can lower effort to High.

Cosa fare:

• Abbassa il livello di sforzo a high o inferiore.
• Riattiva il ragionamento, ad esempio annullando MAX_THINKING_TOKENS o rimuovendo "alwaysThinkingEnabled": false dalle tue impostazioni.

Prima della v2.1.242, Claude Code mostrava il messaggio proprio dell'API: API Error: 400 output_config.effort 'xhigh' is not supported when thinking is disabled on this model. Use effort 'high' or below, or enable thinking. Prima della v2.1.251, Claude Code inviava la richiesta al livello di sforzo che hai impostato, quindi Opus 5 rifiutava ogni richiesta superiore a high con il ragionamento disattivato. Claude Code ora invia invece lo sforzo high ai modelli che sa rifiutano la combinazione, come Opus 5.

Il budget di ragionamento supera il limite di output

Il budget di ragionamento esteso configurato supera la lunghezza massima della risposta, quindi non c'è spazio rimasto per la risposta effettiva.

API Error: 400 ... max_tokens must be greater than thinking.budget_tokens

Cosa fare:

• Aumenta CLAUDE_CODE_MAX_OUTPUT_TOKENS al di sopra del budget di ragionamento
• Vedi Ragionamento esteso per come il budget interagisce con la lunghezza dell'output

Mancata corrispondenza dei blocchi di uso degli strumenti o di ragionamento

La cronologia della conversazione ha raggiunto l'API in uno stato incoerente.

API Error: 400 due to tool use concurrency issues. Run /rewind to recover the conversation.
API Error: 400 orphaned tool_result in conversation history. Run /rewind to recover the conversation.
API Error: 400 duplicate tool_use ID in conversation history. Run /rewind to recover the conversation.
API Error: 400 ... unexpected `tool_use_id` found in `tool_result` blocks
API Error: 400 ... thinking blocks ... cannot be modified

Tutte le varianti significano la stessa cosa: la sequenza di blocchi tool_use, tool_result e thinking nella cronologia non corrisponde più a ciò che l'API si aspetta.

Cosa fare:

• Se stai usando Opus 4.7 o Opus 4.8, esegui prima claude update. Le versioni precedenti alla v2.1.156 possono attivare questo errore durante il normale uso degli strumenti, e /rewind non lo cancella.
• Esegui /rewind, o premi Esc due volte, per tornare indietro a un checkpoint prima del turno corrotto e continua da lì. Vedi Checkpointing per come i checkpoint vengono creati e ripristinati.

Dati non validi nel blocco redacted\_thinking

L'API ha rifiutato la richiesta con un 400 perché non poteva accettare un blocco redacted_thinking che un turno precedente nella cronologia della conversazione porta.

API Error: 400 ... Invalid `data` in `redacted_thinking` block

Claude Code lascia il ragionamento precedente della conversazione fuori dalla richiesta e ritenta una volta, quindi la sessione continua senza mostrare l'errore. Prima della v2.1.282, Claude Code manteneva il blocco rifiutato, e ogni turno successivo falliva con lo stesso errore.

Cosa fare:

• Se sei sulla v2.1.281 o precedente e ogni turno fallisce con questo errore, esegui claude update e riprendi la sessione
• Se l'errore persiste, esegui /clear per avviare una conversazione che non porta il blocco

Contenuto dello strumento non supportato rimosso

Quando Claude Code si connette direttamente all'API Anthropic e carica o visualizza un'anteprima di una sessione salvata, rimuove il contenuto dello strumento che l'API Anthropic non accetta e lascia questa riga dove il contenuto rimosso si trovava tra due blocchi di ragionamento:

[Unsupported tool content removed]

Tale contenuto raggiunge un file di sessione quando qualcosa di diverso dall'API Anthropic ha risposto nel formato dell'API, tipicamente un proxy di terze parti impostato tramite ANTHROPIC_BASE_URL che traduce le chiamate agli strumenti di un altro provider. Claude Code lo rimuove solo quando la sessione si connette direttamente all'API Anthropic, e carica la cronologia salvata come è quando la sessione viene eseguita tramite un proxy o su un altro provider. Prima della v2.1.246, Claude Code inviava l'uso dello strumento e il suo risultato di nuovo all'API, e ogni turno della sessione ripresa falliva con un errore 400 come messages.1.content.0.server_tool_use.name: Input should be 'web_search', 'web_fetch', ....

Cosa fare:

• Nessuno necessario quando vedi la riga segnaposto. La sessione continua senza il contenuto rimosso.
• Se ogni turno di una sessione ripresa fallisce invece con l'errore 400, esegui claude update e riprendi la sessione di nuovo. Le versioni precedenti alla v2.1.246 non rimuovono il contenuto.

Il ruolo 'system' deve precedere un messaggio 'assistant'

L'API ha rifiutato la richiesta con un 400 perché un messaggio di sistema si trova in una posizione nella conversazione che non accetta:

API Error: 400 messages.6: role 'system' must precede an 'assistant' message or end the array; ...

Claude Code invia parte del suo testo di promemoria e allegato come messaggi di sistema all'interno della conversazione. Quando l'API rifiuta la posizione di uno, Claude Code ritenta la richiesta una volta con quel testo inviato come messaggi utente ordinari. Le diciture di posizionamento fratello dell'API, come use the top-level 'system' parameter for the initial system prompt, ottengono lo stesso recupero.

Quando l'errore appare, il messaggio di sistema rifiutato non è uno che Claude Code può rimuovere. Questo di solito significa che un proxy o gateway LLM tra Claude Code e l'API ha aggiunto un messaggio di sistema proprio.

Cosa fare:

• Se l'errore si ripete ad ogni turno dietro un proxy o gateway configurato tramite ANTHROPIC_BASE_URL, connettiti senza il proxy per confermare la fonte, e segnala l'errore a chi lo gestisce
• Esegui /clear per avviare una conversazione fresca. Se l'errore ritorna anche lì, la causa è sul percorso della richiesta, non nella conversazione salvata.

Prima della v2.1.280, Claude Code non riconosceva questa dicitura, quindi l'errore appariva anche quando il messaggio di sistema rifiutato era uno che Claude Code stesso inviava, e ogni turno successivo della conversazione falliva allo stesso modo.

Encrypted\_content non valido nel blocco search\_result

L'API ha rifiutato la richiesta con un 400 perché la cronologia della conversazione contiene contenuto di ricerca web ospitato che non può decrittare. La dicitura nomina il campo che non può leggere:

API Error: 400 ... Invalid `encrypted_content` in `search_result` block
API Error: 400 ... Invalid `encrypted_index` in `text` block
API Error: 400 ... Failed to decrypt web search result content
API Error: 400 ... Invalid `encrypted_stdout` in `encrypted_code_execution_result` block

I risultati dello strumento di ricerca web ospitato dell'API portano campi crittografati che solo l'API può leggere. La dicitura encrypted_stdout nomina l'output di un programma di esecuzione del codice ospitato che ha letto tali risultati, che l'API crittografa anche. L'API rifiuta una richiesta che riproduce il contenuto che non può decrittare, come il contenuto prodotto per un'organizzazione diversa.

Lo strumento WebSearch proprio di Claude Code registra i risultati della ricerca come testo semplice, quindi questi blocchi di solito raggiungono una conversazione tramite un proxy o gateway LLM che ha eseguito la ricerca web ospitata stesso.

Per le tre diciture di ricerca web, Claude Code lascia le chiamate di ricerca, i risultati e le citazioni fuori da ciò che invia e ritenta la richiesta una volta, quindi la sessione continua senza mostrare l'errore. La dicitura encrypted_stdout non ha tale recupero, quindi quel messaggio ti raggiunge comunque. Prima della v2.1.282, Claude Code manteneva anche i blocchi di ricerca web rifiutati, e ogni turno successivo e /compact falliva allo stesso modo.

Cosa fare:

• Se sei sulla v2.1.281 o precedente e ogni turno fallisce con una delle diciture di ricerca web, esegui claude update e riprendi la sessione
• Se l'errore persiste, o il messaggio nomina encrypted_stdout, esegui /rewind per tornare indietro a un checkpoint prima del turno che ha aggiunto il contenuto, oppure esegui /clear per avviare una conversazione che non lo porta
• Se esegui Claude Code dietro un proxy o gateway, segnala l'errore a chi lo gestisce

Rifiuto della politica di utilizzo

L'API ha rifiutato di rispondere perché il contenuto nella conversazione ha attivato un controllo della Politica di utilizzo.

Il messaggio include un ID richiesta e un ID messaggio che puoi citare al supporto se ritieni che il rifiuto sia errato.

API Error: Opus 4.6 can't help with this. Start a new session to continue.

Send feedback with /feedback or learn more: https://www.anthropic.com/legal/aup

Il messaggio nomina il modello che ha rifiutato, o Claude quando nessun modello è registrato.

Il controllo valuta l'intera conversazione, non solo il tuo ultimo prompt, quindi inviare un nuovo messaggio nella stessa sessione di solito ri-attiva lo stesso rifiuto. Lo stesso si applica dopo l'uscita e la riapertura della sessione con --continue o --resume, poiché la trascrizione su disco contiene ancora il contenuto che attiva. Su Amazon Bedrock, Google Cloud's Agent Platform, e Microsoft Foundry, questo messaggio copre anche le richieste che le misure di sicurezza del modello hanno contrassegnato come un argomento di cibersicurezza. Vedi Le misure di sicurezza hanno contrassegnato un argomento di cibersicurezza.

Prima della v2.1.219, il messaggio recitava Claude Code is unable to respond to this request, which appears to violate our Usage Policy (https://www.anthropic.com/legal/aup). Please double press esc to edit your last message or start a new session for Claude Code to assist with a different task.

Cosa fare:

• Premi Esc due volte o esegui /rewind per tornare indietro a un checkpoint prima del turno che ha attivato il rifiuto, quindi riformula o prendi un approccio diverso. Vedi Checkpointing.
• Se non riesci a identificare quale turno l'ha causato, esegui /clear per avviare una conversazione fresca nello stesso progetto. La tua conversazione precedente è preservata su disco e rimane disponibile in /resume.
• In modalità non interattiva (-p), dove il rewind non è disponibile, ritenta con un prompt riformulato in una nuova sessione senza --continue. I controlli della politica variano in base al modello, quindi passare a un modello diverso con --model può anche risolvere il rifiuto in alcuni casi.

Le misure di sicurezza hanno contrassegnato un argomento di cibersicurezza

Le misure di sicurezza del modello hanno contrassegnato il contenuto nella conversazione come un argomento di cibersicurezza. Il messaggio nomina il modello che ha contrassegnato la richiesta:

API Error: Opus 4.8's safeguards flagged this message. Our intentionally broad safeguards allow us to deliver more capabilities faster, but can sometimes flag legitimate cybersecurity work. Apply to the Cyber Verification Program to reduce these interruptions. Send feedback with /feedback or learn more: https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude

Il messaggio si collega al Cyber Verification Program, che concede l'accesso per il lavoro di cibersicurezza legittimo. Su Opus 5.5 e Sonnet 5.5, il messaggio si apre invece con <model>'s safeguards flagged this session. Quando la categoria contrassegnata ha un modello di fallback disponibile, Claude Code cambia modelli piuttosto che mostrare questo errore.

Su Amazon Bedrock, Google Cloud's Agent Platform, e Microsoft Foundry, un flag di cibersicurezza produce invece il messaggio di rifiuto della politica di utilizzo.

La salvaguardia stessa è lato server e precede la v2.1.203; i rilasci client da allora hanno cambiato solo la dicitura del messaggio. Dalla v2.1.203 alla v2.1.218, il messaggio recitava <model> has safety measures that flagged this message for a cybersecurity topic. To learn about the Cyber Verification Program and apply for access, visit our help center: seguito dallo stesso link del centro assistenza, e le sessioni interattive aggiungevano If you were not engaging in a cybersecurity topic, please send feedback via /feedback. Prima della v2.1.203, recitava <model>'s safeguards flagged this message for a cybersecurity topic. If your work requires this access, you can apply for an exemption: seguito da un link del modulo di esenzione.

Cosa fare:

• Se il tuo lavoro richiede questo contenuto, richiedi l'accesso tramite il Cyber Verification Program
• Se la tua richiesta non riguardava un argomento di cibersicurezza, esegui /feedback per segnalare il falso positivo
• Per continuare a lavorare nella stessa sessione, premi Esc due volte o esegui /rewind per tornare indietro a un checkpoint prima del turno che ha attivato il flag, quindi prendi un approccio diverso. Vedi Checkpointing.

Errori di installazione

Questi errori compaiono durante l'installazione o l'aggiornamento di Claude Code, dallo script di installazione, claude install, o claude update. Per i problemi di command not found, PATH, permessi e TLS durante la configurazione, vedere Risoluzione dei problemi di installazione e accesso.

L'installazione è stata interrotta prima di poter terminare

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 è solitamente il killer out-of-memory (OOM) 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 della memoria insufficiente. Il messaggio proviene dallo script di installazione che macOS e Linux utilizzano, che copre anche le installazioni all'interno di WSL; gli script di installazione nativi di Windows non lo stampano mai. Prima della v2.1.200, lo script usciva con solo la riga Killed nuda della shell.

Cosa fare:

• Interrompere altri processi per liberare memoria, quindi eseguire nuovamente il programma di installazione
• Aggiungere spazio di swap o passare a un'istanza più grande. Vedere Installazione interrotta su server Linux con poca memoria per i comandi del file di swap.

La connessione è stata interrotta durante il download dell'aggiornamento

La connessione al server di download si è chiusa mentre claude install o claude update stava recuperando il binario di Claude Code, e i tentativi di ripetizione non hanno recuperato. Claude Code ritenta il download quando la connessione si interrompe, il trasferimento si blocca, o il file scaricato non supera il checksum, fino a tre tentativi in totale. Un errore HTTP completato, come un 404, non viene ritentato perché il server ha già risposto. Prima della v2.1.202, una singola connessione interrotta faceva fallire il download immediatamente con il semplice errore aborted invece di ritentare.

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

Il testo tra parentesi nomina quale tentativo ha fallito e l'errore di rete sottostante. claude update precede il messaggio con Error: Failed to install native update su stderr.

Un download che rimane connesso ma non termina entro 10 minuti fallisce con Download timed out: exceeded the total deadline invece. Claude Code non ritenta un download scaduto, perché una connessione troppo lenta per terminare entro il limite non terminerà nemmeno con un tentativo immediato. I passaggi seguenti si applicano a 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:

• Eseguire claude update di nuovo. Su una rete altrimenti sana, il download di solito ha successo alla prossima esecuzione. Per il messaggio di timeout, eseguirlo di nuovo da una rete più veloce o meno limitata.
• Se la rete richiede un proxy, impostare HTTPS_PROXY prima di eseguire il programma di installazione o claude update. Vedere Verificare la connettività di rete.
• Se un proxy aziendale continua a chiudere il trasferimento, chiedere al team di rete di consentire il download completo da downloads.claude.ai. Vedere Requisiti di accesso alla rete.
• Eseguire claude doctor dalla shell per la diagnostica dell'installazione

Errori della riga di comando

Questi errori provengono dalla riga di comando claude e dai suoi sottocomandi, da un nome di comando che invii al prompt e da comandi come /security-review che raccolgono contesto eseguendo comandi della shell prima che venga eseguito il loro prompt. Provengono anche da /tui, che riavvia la CLI.

Conflitto tra `--bg` e `--print`

Questo messaggio richiede Claude Code v2.1.198 o versioni successive. Hai combinato --bg con -p o --print nella stessa invocazione di claude. --bg avvia una sessione in background a cui ti colleghi in seguito con claude agents, mentre --print viene eseguito in modalità non interattiva e non avvia mai la sessione interattiva a cui si collega claude agents. Prima della v2.1.198 questa combinazione creava silenziosamente un job in background a cui non era mai possibile collegarsi.

--bg and --print conflict: --print never starts the interactive session that `claude agents` attaches to, so the job would be unattachable. The prompt is the positional — drop --print: `claude --bg '<task>'`.

Cosa fare:

• Rimuovi -p o --print. --bg accetta il prompt come argomento posizionale, quindi claude --bg "<task>" è il comando completo. Consulta Avviare nuovi agenti dalla shell.
• Per eseguire il prompt in modo non interattivo e stampare il risultato invece di creare una sessione in background, rimuovi --bg ed esegui claude -p "<task>"

Conflitto tra un flag del prompt di sistema e la sua forma su file

Hai passato --append-subagent-system-prompt insieme a --append-subagent-system-prompt-file in un'unica invocazione di claude, quindi claude termina con codice di uscita 1 invece di avviare la sessione:

Error: Cannot use both --append-subagent-system-prompt and --append-subagent-system-prompt-file. Please use only one.

Prima della v2.1.283, claude terminava allo stesso modo quando passavi --system-prompt con --system-prompt-file, oppure --append-system-prompt con --append-system-prompt-file, perché quelle coppie entravano in conflitto invece di combinarsi. In quelle versioni il messaggio indica la coppia che hai combinato.

Cosa fare:

• Mantieni una forma del flag e rimuovi l'altra. Per combinare un file di prompt fisso con testo specifico per ogni esecuzione, unisci il testo nel file prima dell'avvio invece di passare entrambi i flag

Configurazione `--agents` non valida

Il valore che hai passato a --agents non è valido, quindi claude termina con codice di uscita 1 invece di avviare la sessione. Quando passi --safe-mode o imposti CLAUDE_CODE_SAFE_MODE, Claude Code ignora completamente --agents. Con --resume o --continue, un valore JSON inline non viene verificato e la sessione si avvia; un valore letto da un file viene verificato a ogni avvio. Prima della v2.1.242, Claude Code avviava comunque la sessione.

Error: Invalid --agents configuration:
<what failed>

Ciò che segue la prima riga dipende da come il valore non è risultato valido. Claude Code esegue questi controlli in ordine e si ferma al primo che fallisce. Se il tuo valore presenta due tipi di problema, vedi il secondo solo dopo aver corretto il primo:

1. Quando il valore inizia con { ma non viene analizzato come JSON, oppure il contenuto di un file --agents non viene analizzato, Claude Code stampa una riga invalid JSON: che riporta il messaggio del parser JSON stesso
2. Quando viene analizzato ma una definizione di agente non corrisponde allo schema per i subagent definiti tramite CLI, Claude Code stampa una riga per ogni problema
3. Quando il nome di un agente inizia con -, Claude Code stampa <name>: agent names must not start with '-'

Quando ci sono più di 20 righe di problemi, Claude Code stampa le prime 20 e sostituisce le restanti con …and N more.

Con --print, --agents accetta anche il percorso di un file JSON al posto dell'oggetto inline. Prima della v2.1.281, --agents accettava solo JSON inline e trattava un percorso di file come JSON non valido. La forma su file ha i propri rifiuti, stampati al posto di questo messaggio, tra cui questi:

• Error: --agents takes a JSON object, or a file path only with --print (-p): Claude Code ha letto il valore come percorso di file in una sessione interattiva. Passa le definizioni come JSON inline, oppure aggiungi -p per leggerle da un file.
• Error: --agents file not found: <path>: non esiste alcun file in quel percorso. Un valore che non inizia con { e non è JSON valido viene letto come percorso, quindi anche un JSON inline alterato dalla tua shell può fallire in questo modo. Controlla il percorso o le virgolette ed esegui di nuovo il comando.

Cosa fare:

• Correggi ogni problema elencato nel messaggio, quindi esegui di nuovo il comando. Consulta i campi accettati da un subagent definito tramite CLI.

Non è possibile creare sessioni cloud da una sessione `--restricted`

Quando avvii una sessione con --restricted, Claude Code si rifiuta di creare sessioni cloud a partire da essa, perché la nuova sessione verrebbe eseguita al di fuori del processo con restrizioni e non applicherebbe la modalità con restrizioni. Claude Code rifiuta lato client, prima di contattare il server, quindi non viene creata alcuna sessione cloud:

Cloud sessions cannot be created from a --restricted session: they would not enforce it.

Cosa fare:

• Esegui l'attività localmente nella sessione con restrizioni
• Se controlli il modo in cui è stata avviata la sessione, avvia una nuova sessione claude senza --restricted e crea la sessione cloud da lì

Prima della v2.1.248, Claude Code non aveva il flag --restricted; le versioni precedenti rifiutano il flag stesso con un errore di opzione sconosciuta.

Le sessioni cloud sono disabilitate dalla policy della tua organizzazione

La policy allow_remote_sessions della tua organizzazione è disattivata, quindi le sessioni cloud e i comandi che le usano non sono disponibili:

Cloud sessions are disabled by your organization's policy. Contact your organization admin to enable them.

Il messaggio appare quando crei una sessione cloud dal terminale e quando invii un comando che richiede le sessioni cloud, come /teleport, /remote-env o /web-setup. Prima della v2.1.268, l'invio di uno di quei comandi restituiva invece Unknown command.

Si tratta di una policy dell'organizzazione lato server, quindi non può essere sovrascritta da impostazioni locali, variabili d'ambiente o flag della CLI.

Se Claude Code non ha ancora caricato la policy della tua organizzazione o non riesce a recuperarla, quei comandi rispondono invece con Couldn't verify your organization's policy for cloud sessions. Check your network connection, then restart Claude Code and try again..

Cosa fare:

• Chiedi a un Owner della tua organizzazione di abilitare le sessioni cloud nelle impostazioni di amministrazione di Claude Code su claude.ai/admin-settings/claude-code
• Se il messaggio dice che non è stato possibile verificare la policy, controlla la connessione di rete, quindi riavvia Claude Code e riprova

Il valore di `--json-schema` non è un JSON Schema valido

Lo schema che hai passato a --json-schema in modalità non interattiva non ha superato la compilazione JSON Schema, quindi claude termina con codice di uscita 1 invece di eseguire il prompt. Prima della v2.1.205, uno schema non valido produceva un output non strutturato senza alcun errore, e qualsiasi schema che usasse la parola chiave format veniva trattato come non valido.

Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values

Il testo dopo i secondi due punti è la diagnostica del validatore e indica la parola chiave o la posizione che non ha superato la verifica. Gli schemi che usano la parola chiave format, come "format": "email", sono validi: Claude Code accetta format come annotazione e non lo applica.

Claude Code esegue due controlli prima della compilazione dello schema: rifiuta un valore che non è JSON analizzabile con Error: --json-schema is not valid JSON, e un JSON valido che non è un oggetto con Error: --json-schema must be a JSON object.

Cosa fare:

• Correggi la parte dello schema indicata dalla diagnostica, quindi esegui di nuovo il comando
• Consulta Ottenere output strutturato per uno schema e un comando funzionanti

Il file di impostazioni supera il limite di 2MiB

Il file che hai passato a --settings è più grande di 2 MiB, quindi claude termina con codice di uscita 1 all'avvio invece di caricarlo. Prima della v2.1.214, Claude Code leggeva il file senza alcun controllo sulla dimensione, e un file di diversi gigabyte o un file di dispositivo come /dev/zero facevano crescere la memoria senza limiti.

Error: Settings file exceeds the 2MiB limit: /path/to/settings.json

Claude Code rifiuta allo stesso modo un percorso --settings che non è un file regolare: un dispositivo, una FIFO o un socket riporta Error: Cannot use settings file (Not a regular file (device, FIFO, or socket)) seguito dal percorso, e una directory riporta un motivo EISDIR.

Cosa fare:

• Indica a --settings un file di impostazioni JSON regolare inferiore a 2 MiB. Consulta Impostazioni per il formato.

La directory corrente non esiste più

Hai avviato claude da una directory che è stata eliminata o spostata dopo che la tua shell vi è entrata, ad esempio un worktree o una directory temporanea rimossa da un'altra shell. Claude Code non riesce a leggere la propria directory di lavoro, quindi termina con codice di uscita 1 prima di avviare la sessione, sia in modalità interattiva sia in modalità non interattiva. Prima della v2.1.239, Claude Code andava in crash mostrando su stderr il sorgente minificato del bundle e uno stack ENOENT ... uv_cwd grezzo invece di questo messaggio.

The current directory no longer exists (it was deleted or moved). Start Claude Code from an existing directory.
error: The current working directory was deleted, so that command didn't work. Please cd into a different directory and try again.

La causa e la soluzione sono le stesse per entrambe le forme.

Quando Claude Code non riesce a leggere la directory di lavoro per un motivo diverso, come una modifica dei permessi, il messaggio indica invece il codice di errore: Can't read the current directory (EACCES). Start Claude Code from a different directory.

Su macOS, EPERM per una directory in ~/Desktop, ~/Documents, ~/Downloads o iCloud Drive di solito significa che macOS sta bloccando l'accesso della tua app del terminale a quella cartella. Anche altri comandi che leggono quella cartella falliscono allo stesso modo: ls in quella posizione riporta Operation not permitted, anche con sudo.

Cosa fare:

• Passa a una directory esistente, come la tua directory home o la directory del progetto, quindi esegui di nuovo claude
• Se la directory è stata ricreata nello stesso percorso, la tua shell mantiene ancora quella eliminata. Esegui cd "$PWD" oppure esci dalla directory e rientraci, quindi esegui di nuovo claude
• Per EPERM su macOS, chiudi la tua app del terminale con Cmd+Q, riaprila, torna in quella cartella ed esegui claude. Se ls in quella cartella continua a fallire, apri Impostazioni di Sistema > Privacy e sicurezza > File e cartelle, attiva la cartella per la tua app del terminale, quindi riapri il terminale

Directory temporanea rifiutata o impossibile da creare

Su macOS e Linux, Claude Code crea all'avvio una directory temporanea privata, claude-<uid>, nella directory temporanea di sistema o nell'override CLAUDE_CODE_TMPDIR. Quando la directory non può essere creata, o una voce già presente in quel percorso non supera i controlli di sicurezza, Claude Code stampa l'errore su stderr e termina con codice di uscita 1 invece di avviare la sessione:

ENOSPC: no space left on device, mkdir '/tmp/claude-501'

Temp directory /tmp/claude-501 is not a directory (may be an attacker-planted symlink). Refusing to use it. Set CLAUDE_CODE_TMPDIR to a directory you control, or ask an administrator to remove it.

Temp directory /tmp/claude-501 is owned by uid 502, expected 501. Refusing to use it — another user may have pre-created it. Set CLAUDE_CODE_TMPDIR to a directory you control, or ask an administrator to remove it.

Temp directory /tmp/claude-501 is not readable (its mode may have been altered, or a path component denies search). Refusing to use it — restore its permissions (chmod 0700) or remove it. Set CLAUDE_CODE_TMPDIR to a directory you control, or ask an administrator to remove it.

Cosa fare:

• Per ENOSPC, libera spazio su disco nel volume che contiene la directory temporanea
• Per le forme Refusing to use it, rimuovi la voce indicata stessa, non ciò a cui punta un collegamento, e avvia di nuovo Claude Code; per la forma owned by uid, solo un amministratore o quell'utente può rimuoverla
• Per is not readable, esegui chmod 0700 sulla directory indicata, oppure rimuovila e avvia di nuovo
• In tutti questi casi, imposta CLAUDE_CODE_TMPDIR su una directory che controlli e avvia di nuovo Claude Code, lasciando intatto il percorso rifiutato

Non è stato possibile risolvere la directory in una posizione reale

Hai eseguito /add-dir per una sottodirectory della tua directory di lavoro e Claude Code non è riuscito a risolvere la directory nella sua posizione reale.

Hai già accesso ai file di una sottodirectory della directory di lavoro, quindi /add-dir carica solo le sue skill, i suoi comandi e i suoi agenti. Prima di caricarli, Claude Code verifica che la posizione reale della directory, con eventuali collegamenti simbolici risolti, si trovi all'interno della directory di lavoro. Quando Claude Code non riesce a risolvere quella posizione, non carica nulla e mostra questo messaggio:

packages/app couldn't be resolved to a real location, so its skills, commands, and agents weren't loaded. Check that it is a directory inside the working directory and try again.

Cosa fare:

• Verifica che il percorso indichi una directory reale all'interno della directory di lavoro, quindi esegui di nuovo /add-dir
• Il messaggio non modifica il tuo accesso ai file; segnala solo che il contenuto .claude/ della directory non è stato caricato

Prima della v2.1.261, questo messaggio appariva anche per ogni /add-dir <subdirectory> quando la directory di lavoro si trovava su un automount /net/<host>, dove Claude Code per scelta progettuale non risolve i percorsi; la directory era a posto e riprovare non poteva aiutare.

Workspace non attendibile all'avvio di Remote Control

Hai avviato la modalità server di Remote Control con claude remote-control o il suo alias claude rc in una directory che non hai contrassegnato come attendibile, e il comando non è riuscito a chiederti se considerarla attendibile. Ad esempio, lo standard input o lo standard output del comando non è un terminale perché uno dei due è reindirizzato o collegato tramite pipe. Il comando termina con codice di uscita 1:

Error: Workspace not trusted. Please run `claude` in /Users/you/project first to review and accept the workspace trust dialog.

Due varianti che iniziano anch'esse con Error: Workspace not trusted. appaiono in un terminale troppo piccolo per mostrare cosa attiva il considerare attendibile la directory, o in uno che non ha riportato le proprie dimensioni. Ingrandisci la finestra o passa a una normale finestra del terminale, quindi esegui di nuovo claude rc.

Nella tua directory home il messaggio è diverso, perché la finestra di dialogo di attendibilità del workspace non salva mai l'attendibilità per la directory home, quindi accettarla lì non può soddisfare questo controllo. Prima della v2.1.214, la directory home mostrava il messaggio precedente, il cui consiglio non può funzionare in quella posizione.

Error: Workspace not trusted. /Users/you is your home directory, and for security home-directory trust is never saved, so running `claude` here first won't help. Run `claude rc` from a project directory instead (run `claude` there once to accept the trust dialog).

Se rispondi n o premi Invio alla domanda Trust <directory>?, il comando stampa un messaggio Remote Control did not start che indica la directory e termina con codice di uscita 1. Esegui di nuovo claude rc per rispondere y.

Cosa fare:

• Prima rendi attendibile la directory da un terminale: esegui claude rc lì e rispondi y, oppure esegui claude lì e accetta la finestra di dialogo di attendibilità del workspace, quindi esegui di nuovo il comando originale
• Nella tua directory home, passa a una directory di progetto e avvia Remote Control da lì

Prima della v2.1.284, il comando non lo chiedeva mai, nemmeno in un terminale.

Non trasferito alle sessioni avviate da Remote Control

Hai avviato Remote Control con un flag globale di claude prima del verbo remote-control, uno che limiterebbe o configurerebbe le sessioni avviate da Remote Control, come --settings, --setting-sources, --permission-mode, --disallowed-tools o --mcp-config. Un flag posto prima del verbo non raggiunge mai quelle sessioni. Claude Code si rifiuta invece di avviarsi, indicando il flag:

Error: `--settings` before `remote-control` is not carried over to the sessions Remote Control starts, so Remote Control refuses to start rather than drop it — remove it, and give Remote Control's own options after the verb (see `claude remote-control --help`).

Claude Code non rifiuta i flag globali che è innocuo scartare, come --verbose, --model, o un --session-id o --plugin-dir inserito da un wrapper: li ignora e Remote Control si avvia.

Claude Code si rifiuta di avviarsi anche per un flag globale che non riconosce ancora come innocuo, quindi un flag aggiunto in una release più recente può apparire in questo messaggio finché una release successiva non lo contrassegna come innocuo.

Cosa fare:

• Rimuovi il flag da prima del verbo e passa le opzioni proprie di Remote Control dopo di esso; claude remote-control --help le elenca
• Quando il flag rifiutato è --permission-mode, esegui claude remote-control --permission-mode <mode> per impostare la modalità di permesso per le sessioni avviate da Remote Control

Prima della v2.1.248, claude remote-control non accettava i propri flag quando veniva prima un flag globale, e il comando falliva con un errore unknown option.

claude import non è ancora disponibile in questa build

Hai eseguito claude import e Claude Code ha rilevato che il flusso di importazione è disattivato, quindi il comando termina con codice di uscita 1 invece di avviare l'importazione. Prima della v2.1.222, una build con il flusso di importazione disattivato trattava import come un prompt e avviava una sessione interattiva invece di stampare questo messaggio.

`claude import` is not yet available in this build. Run `claude` and use /mcp or edit ~/.claude/settings.json directly.

Claude Code attiva claude import tramite un feature flag che recupera da Anthropic e memorizza nella cache su disco. Questo messaggio significa che il valore nella cache è disattivato. La causa è di solito una delle seguenti:

• Non hai avviato una sessione dall'installazione, quindi Claude Code non ha ancora recuperato il flag. Il primo claude import può stampare questo messaggio anche quando la funzionalità è disponibile per te.
• Usi Claude Code tramite Amazon Bedrock, Agent Platform di Google Cloud, Microsoft Foundry o Claude Platform on AWS, oppure tramite un gateway delle app Claude. Claude Code non recupera i feature flag in queste sessioni, quindi claude import resta non disponibile.
• Hai impostato DISABLE_TELEMETRY, DO_NOT_TRACK, DISABLE_GROWTHBOOK o CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, che disattivano il recupero dei feature flag, quindi claude import resta non disponibile.

Cosa fare:

• Su una nuova installazione, avvia claude, attendi che la sessione venga caricata, esci ed esegui di nuovo claude import
• Dove il recupero dei feature flag resta disattivato, imposta tu stesso la configurazione: aggiungi i server MCP con claude mcp add e crea i file CLAUDE.md, le skill e i comandi e i subagent che vuoi trasferire. Il messaggio indica anche ~/.claude/settings.json. Della configurazione che claude import trasferisce, quel file contiene solo la modalità di permesso; Claude Code non legge i server MCP da esso.

Impossibile leggere la configurazione di Claude Code

Hai eseguito claude import mentre Claude Code non riusciva ad analizzare ~/.claude.json, il file in cui memorizza il tuo accesso e lo stato per progetto. Il sottocomando legge quel file per verificare la disponibilità, ma non mostra la finestra di dialogo di ripristino che mostra la sessione interattiva, quindi termina con codice di uscita 1. Prima della v2.1.222, claude import con un file di configurazione illeggibile avviava una sessione interattiva, la cui finestra di dialogo di ripristino gestiva il file.

Could not read Claude Code config — run `claude` with no arguments to recover it.

Cosa fare:

• Esegui claude senza argomenti. Claude Code rileva il file non valido e offre di reimpostarlo. Quindi esegui di nuovo claude import.
• Per mantenere le modifiche manuali che hai apportato, correggi invece la sintassi JSON in ~/.claude.json in un editor, quindi esegui di nuovo claude import

Impossibile importare un server da Claude Desktop

Claude Code non è riuscito ad aggiungere uno dei server che hai selezionato in claude mcp add-from-claude-desktop. Il comando importa comunque gli altri server selezionati e stampa una riga per ogni server che non è riuscito ad aggiungere. Prima della v2.1.205, il primo server che falliva interrompeva l'importazione.

Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.

Il testo dopo il nome del server è il motivo. Il più comune è il controllo del nome: Claude Desktop consente nei nomi dei server caratteri, come spazi e punti, che claude mcp limita a lettere, numeri, trattini e trattini bassi. Altri motivi includono una configurazione del server che non supera la validazione e un server bloccato dalla policy MCP della tua organizzazione.

Cosa fare:

• Rinomina il server in claude_desktop_config.json usando solo lettere, numeri, trattini e trattini bassi, quindi esegui di nuovo claude mcp add-from-claude-desktop
• Aggiungi quel server direttamente con claude mcp add o claude mcp add-json con un nome valido. Consulta Importare server MCP da Claude Desktop.

Impossibile aggiungere un server MCP all'ambito managed

Hai eseguito claude mcp add o claude mcp add-json con --scope managed. Quell'ambito contiene i server che la tua organizzazione fornisce tramite l'impostazione gestita managedMcpServers. Claude Code li legge solo dalle impostazioni gestite, quindi il comando non può scrivere un server in quell'ambito.

Cannot add MCP server to scope: managed

Cosa fare:

• Aggiungi il server a un ambito in cui puoi scrivere: local, user o project. Senza --scope, il comando usa local. Consulta Ambiti di installazione MCP
• Per fornire il server a ogni utente della tua organizzazione, aggiungilo a managedMcpServers nelle impostazioni gestite che distribuisci

Impossibile aggiungere un server MCP quando le impostazioni gestite consentono solo server dei plugin

Hai eseguito claude mcp add o claude mcp add-json mentre le impostazioni gestite della tua organizzazione impostano strictPluginOnlyCustomization su true o su un elenco che include mcp. Con questa impostazione, Claude Code non carica i server MCP da ~/.claude.json o .mcp.json, quindi il comando termina con codice di uscita 1 invece di salvare un server che non verrebbe mai caricato:

Cannot add MCP server: your organization's managed settings allow only MCP servers that plugins provide. Install a plugin that provides this server, or ask your administrator to make it available.

claude mcp add-from-claude-desktop segnala ogni server che selezioni come non importato, con questo messaggio come motivo. /import riporta questo messaggio per ogni server MCP che tenta di aggiungere e importa comunque gli altri elementi che ha trovato.

Prima della v2.1.284, questi comandi salvavano il server e segnalavano il successo, e il server non veniva mai caricato.

Cosa fare:

• Installa un plugin che fornisce il server
• Chiedi al tuo amministratore di distribuire il server in un plugin, oppure di fornirlo tramite managedMcpServers se si tratta di un server HTTP o SSE remoto

Impossibile leggere .mcp.json

Un comando che legge il file .mcp.json del progetto, come claude mcp add o claude mcp add-json con --scope project, oppure claude mcp remove, ha rilevato che il file nella directory corrente non è un file regolare o è più grande di 2 MiB, quindi termina con questo errore invece di leggere il file.

Can't read .mcp.json: it isn't a regular file or is larger than 2097152 bytes. Fix or remove it, then run the command again.

Prima della v2.1.257, una FIFO in .mcp.json lasciava il comando in attesa all'infinito senza output, e un collegamento simbolico a un file di dispositivo come /dev/zero faceva crescere la memoria finché il processo non veniva terminato.

Cosa fare:

• Controlla cosa si trova in .mcp.json nella directory corrente. Sostituiscilo con un normale file JSON nel formato dell'ambito di progetto, oppure eliminalo, quindi esegui di nuovo il comando.

Il server MCP non è stato salvato o rimosso

Hai eseguito claude mcp add, claude mcp add-json o claude mcp remove per un server nell'ambito user o local. Entrambi gli ambiti sono memorizzati in ~/.claude.json, e la modifica non è presente in quel file quando Claude Code lo rilegge dopo la scrittura. Il comando termina con questo errore invece della sua riga di successo.

MCP server "example" was not saved to /home/user/.claude.json. If that file is read-only or protected by a sandbox, make it writable or run the command outside the sandbox, then add the server again.

Dopo una rimozione, il messaggio riporta was not removed from e termina con then remove the server again. Per un server nell'ambito local, il percorso è seguito dalla directory del progetto a cui appartiene la voce, come (local scope for /path/to/project).

Prima della v2.1.283, claude mcp add, claude mcp add-json e claude mcp remove segnalavano il successo anche quando la modifica non raggiungeva il file.

Cosa fare:

• Rendi scrivibile il file indicato dal messaggio, oppure esegui il comando al di fuori della sandbox, quindi esegui di nuovo lo stesso comando di aggiunta o rimozione.

Il server MCP potrebbe non essere stato salvato o rimosso

Hai eseguito claude mcp add, claude mcp add-json o claude mcp remove per un server nell'ambito user o local, e Claude Code non è riuscito a rileggere ~/.claude.json per confermare la modifica. La modifica potrebbe essere su disco oppure no. Il testo tra parentesi è l'errore di quella lettura.

MCP server "example" may not have been saved: /home/user/.claude.json could not be read to confirm the change (EACCES: permission denied, open '/home/user/.claude.json'). Run `claude mcp get example` to check, then add the server again if it is missing.

Dopo una rimozione, il messaggio riporta may not have been removed e termina con then remove the server again if it is still listed.

Prima della v2.1.283, i comandi segnalavano il successo anche quando la modifica non poteva essere confermata.

Cosa fare:

• Esegui claude mcp get <name> per verificare se la modifica è su disco. Per un server nell'ambito local, eseguilo dalla directory del progetto a cui appartiene il server, poiché l'ambito locale è per progetto.
• Se il server manca dopo un'aggiunta, o è ancora elencato dopo una rimozione, esegui di nuovo lo stesso comando di aggiunta o rimozione.

Il server è ospitato da Anthropic e non supporta OAuth locale

Hai avviato l'accesso per un server MCP il cui URL punta a un host di connettori ospitato da Anthropic che esegue l'autenticazione tramite un provider di identità di terze parti. Questi host includono microsoft365.mcp.claude.com, gmail.mcp.claude.com e gcal.mcp.claude.com. Claude Code si rifiuta di avviare il proprio flusso OAuth locale per questi host sia dal pannello /mcp sia da claude mcp login, perché il loro accesso funziona solo tramite claude.ai.

"gmail" is Anthropic-hosted and doesn't support local OAuth. Connect it via Settings → Connectors on claude.ai (requires `claude login`), then it'll be available here automatically.

Cosa fare:

• Rimuovi la tua voce con claude mcp remove <name>, in modo che non possa nascondere il connettore claude.ai allo stesso URL
• Dopo averla rimossa, collega il servizio su claude.ai/customize/connectors, dopo aver effettuato l'accesso con l'account che usi in Claude Code. Una volta collegato, il connettore appare automaticamente in Claude Code se il tuo metodo di autenticazione attivo è un accesso con abbonamento claude.ai

Il server ha rifiutato l'header Authorization generato dall'headersHelper configurato

Un server MCP il cui headersHelper fornisce l'header Authorization ha risposto alla connessione con HTTP 401 o 403, quindi Claude Code segnala la connessione come non riuscita. Poiché l'helper fornisce l'header Authorization, Claude Code non ripiega su OAuth per il server:

Server rejected the Authorization header minted by the configured headersHelper (HTTP 401). Check that the helper command returns a valid credential for this MCP endpoint — OAuth fallback is disabled when the helper supplies Authorization.

Claude Code esegue di nuovo l'helper a ogni tentativo di connessione, quindi un nuovo tentativo dopo un rifiuto temporaneo, come una race condition nella rotazione dei token, può riuscire con una credenziale aggiornata.

Cosa fare:

• Esegui tu stesso il comando headersHelper nel modo in cui lo esegue Claude Code: dalla directory in cui Claude Code lo esegue, con le variabili d'ambiente che Claude Code imposta per esso, e senza le variabili delle credenziali che Claude Code rimuove per un server proveniente da un .mcp.json di progetto, da un plugin o da un file di agente del progetto. Verifica che stampi un valore Authorization accettato dall'endpoint del server
• Dopo aver corretto l'helper o l'origine delle sue credenziali, seleziona il server in /mcp e scegli Reconnect

Prima della v2.1.248, Claude Code eseguiva il discovery OAuth per un server il cui helper forniva l'header Authorization. Quel discovery poteva fallire con Incompatible auth server: does not support dynamic client registration invece di segnalare la credenziale rifiutata.

Strumento di richiesta di permesso MCP non trovato

Lo strumento che hai passato a --permission-prompt-tool non era tra gli strumenti MCP connessi quando l'esecuzione ha avuto bisogno per la prima volta di una decisione sui permessi, o perché il suo server non si è mai connesso o perché nessun server connesso espone uno strumento con quel nome. Claude Code invia comunque il tuo prompt: l'esecuzione non interattiva termina con questo errore, e codice di uscita 1, alla prima chiamata a uno strumento, quindi non produce alcuna risposta anche se la richiesta è stata effettuata. Prima del primo prompt, Claude Code attende che quel server si connetta fino al timeout di connessione per server di 30 secondi impostato da MCP_TIMEOUT. Prima della v2.1.206, l'avvio non attendeva che il server completasse la connessione, quindi anche un server funzionante ma lento ad avviarsi produceva questo errore.

Error: MCP tool mcp__permissions__approve (passed via --permission-prompt-tool) not found. Available MCP tools: none

L'elenco dopo Available MCP tools: indica gli strumenti MCP che erano connessi.

Cosa fare:

• Verifica che il server si avvii e resti connesso: esegui claude mcp list nella stessa directory e conferma che il server sia elencato come connesso
• Conferma che il nome dello strumento corrisponda al nome mcp__<server>__<tool> esposto dal server
• Se il server ha bisogno di più di 30 secondi per avviarsi, aumenta MCP_TIMEOUT

La porta di callback OAuth è già in uso

Quando accedi a un server MCP remoto con OAuth, Claude Code avvia un listener locale per ricevere il callback di accesso. Se la porta di cui ha bisogno quel listener è occupata da un altro processo, l'accesso fallisce con questo messaggio. Questo accade soprattutto con una porta di callback fissa impostata tramite la variabile MCP_OAUTH_CALLBACK_PORT o --callback-port, poiché senza di essa Claude Code sceglie una porta disponibile.

OAuth callback port <port> is already in use — another process may be holding it. Run `lsof -ti:<port> -sTCP:LISTEN` to find it.

Su Windows, il comando suggerito è invece netstat -ano | findstr :<port>.

Cosa fare:

• Esegui il comando indicato nel messaggio per trovare il processo che occupa la porta, e arrestalo o attendi che termini
• Se un altro programma ha bisogno di quella porta in modo permanente, registra un URI di reindirizzamento diverso con il server e imposta la sua porta con MCP_OAUTH_CALLBACK_PORT o --callback-port, a seconda di quale usi
• Quindi avvia di nuovo l'accesso, ad esempio selezionando il server in /mcp

Nessuna porta disponibile per il reindirizzamento OAuth

Quando accedi a un server MCP remoto con OAuth, Claude Code avvia un listener locale per ricevere il callback di accesso. L'accesso fallisce con questo messaggio quando Claude Code non riesce a effettuare il bind di una porta locale per esso. Qualcosa sulla macchina gli impedisce di mettersi in ascolto su 127.0.0.1, ad esempio un software di sicurezza o una policy della sandbox che nega i listener locali.

No available ports for OAuth redirect

Prima della v2.1.268, Claude Code non ripiegava su una porta assegnata dal sistema operativo, quindi il messaggio appariva anche quando non era possibile effettuare il bind solo delle porte scelte da Claude Code stesso. Questo può accadere su host Windows in cui Hyper-V riserva intervalli di porte che coprono le porte tra cui Claude Code sceglie.

Cosa fare:

• Verifica se un software di sicurezza o una policy della sandbox impedisce ai processi di mettersi in ascolto su 127.0.0.1, e consenti a Claude Code di effettuare il bind di una porta locale
• Quindi avvia di nuovo l'accesso, ad esempio selezionando il server in /mcp

/security-review fallisce senza origin/HEAD

/security-review costruisce il contesto della revisione calcolando il diff del tuo branch rispetto a origin/HEAD, il ref locale che registra quale branch è quello predefinito sul tuo remote origin. Quando quel ref non esiste, i comandi git che raccolgono il diff falliscono e la revisione si interrompe prima di iniziare.

Error: Shell command failed for pattern "!`git diff --name-only origin/HEAD...`": [stderr]
fatal: ambiguous argument 'origin/HEAD...': unknown revision or path not in the working tree.
Use '--' to separate paths from revisions, like this:
'git <command> [<revision>...] -- [<file>...]'

Il messaggio potrebbe citare invece git log o un diverso git diff. Git crea origin/HEAD solo quando il remote annuncia un branch predefinito e il tuo refspec di fetch lo include, come avviene con un git clone completo di un remote con dei commit. Il ref manca in queste configurazioni:

• Un checkout single-branch o di CI, che esegue il fetch di un refspec troppo ristretto
• Un remote il cui HEAD lato server punta a un branch su cui nessuno ha eseguito il push
• Un repository senza remote origin, o uno su cui non hai mai eseguito il fetch

Claude Code mostra lo stesso errore per qualsiasi skill che inietta contesto dinamico, e un comando iniettato non riuscito interrompe l'invocazione di quella skill. Due stringhe analoghe vengono generate prima ancora che il comando venga eseguito:

• Shell command permission check failed for pattern "...": il controllo dei permessi del comando non lo ha consentito. Controlli dei permessi sui comandi iniettati spiega quali risultati causano l'interruzione in ciascuna modalità di permesso e come pre-approvare un comando con allowed-tools
• Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found: il frontmatter della skill richiede bash su una macchina che ne è priva. Installa Git for Windows o modifica il frontmatter in shell: powershell. Consulta Come vengono eseguiti i comandi iniettati

Cosa fare:

• Crea il ref indicando il branch predefinito del tuo remote: git remote set-head origin <default-branch>. Questo funziona ogni volta che esiste il ref di tracciamento locale origin/<default-branch>. Se non esiste, come nei clone single-branch, esegui prima il fetch del branch: esegui git remote set-branches --add origin <branch>, poi git fetch origin, quindi esegui di nuovo il comando set-head. Esegui di nuovo /security-review.
• Se preferisci non indicare il branch, esegui git fetch origin e poi git remote set-head origin --auto, che chiede al remote quale branch è quello predefinito. Fallisce con error: Cannot determine remote HEAD quando il remote non annuncia alcun branch predefinito, perché è vuoto o il suo HEAD punta a un branch su cui nessuno ha eseguito il push; in tal caso indica il branch esplicitamente. Fallisce con error: Not a valid ref quando il tuo clone non esegue il fetch di quel branch; prima amplia il refspec come indicato sopra.
• Se il repository non ha un remote, aggiungine uno con git remote add origin <url> ed esegui il fetch prima di creare il ref. Se il remote è vuoto, esegui prima il push del tuo branch con git push -u origin HEAD e indica quel branch nel comando set-head; origin/HEAD punterà quindi al branch di cui hai appena eseguito il push, quindi /security-review vedrà un diff vuoto finché il branch non divergerà da esso.

È necessario fornire un input quando si usa `--print`

claude senza argomenti ha bisogno che stdout sia un terminale per avviare l'interfaccia interattiva. Quando stdout è reindirizzato, o la console non è un vero terminale, come PowerShell ISE e alcuni riquadri di output degli IDE, claude viene invece eseguito in modalità non interattiva. È la stessa modalità di claude -p, che richiede un prompt, quindi il messaggio indica --print anche quando non hai passato il flag. Passare -p/--print senza un prompt e senza nulla inviato tramite pipe su stdin produce lo stesso errore ovunque.

Error: Input must be provided either through stdin or as a prompt argument when using --print

Cosa fare:

• Per l'uso interattivo, esegui claude in un vero terminale: Windows Terminal o la console di PowerShell invece di ISE, e il terminale integrato del tuo IDE invece di un riquadro di output
• Per un uso singolo, passa il prompt: claude -p "your question", oppure invialo tramite pipe con echo "your question" | claude -p

Claude Code non può leggere la tastiera qui

Hai eseguito claude senza -p, il che avvia una sessione interattiva, ma il suo standard input non è un terminale. Qualcosa lo ha collegato tramite pipe o reindirizzato, oppure il programma che ha avviato claude ha fornito il proprio flusso di input.

Una sessione interattiva ha bisogno di un terminale da cui leggere i tuoi tasti, e ciò che Claude Code fa in assenza di uno dipende dalla tua piattaforma:

• Windows: Claude Code stampa il messaggio su stderr e termina con codice di uscita 1 invece di avviare l'interfaccia
• macOS e Linux: Claude Code legge i tuoi tasti da /dev/tty e avvia la sessione, usando l'eventuale testo inviato tramite pipe come primo prompt. Vedi il messaggio quando /dev/tty non può essere aperto, e la sua prima riga indica /dev/tty al posto della formulazione per Windows.

Su Windows il messaggio è:

Claude Code can't read the keyboard here: stdin is not a terminal (it is piped, redirected, or supplied by the program that launched claude), and on Windows it can't fall back to the console for input yet.
Run claude directly in Windows Terminal, PowerShell, or Command Prompt, without piping or redirecting its input.
To send text as a prompt and print the reply instead, add -p; it also works with --continue and --resume <session-id> (for example: type notes.md | claude -p --continue).

Cosa fare:

• Per lavorare in modo interattivo, esegui claude direttamente in un terminale, senza collegare tramite pipe o reindirizzare il suo input
• Per ottenere una risposta senza l'interfaccia interattiva, ad esempio da uno script, aggiungi -p e fornisci il prompt come argomento o su stdin, come in claude -p "your question" o echo "your question" | claude -p. Lo stesso funziona con --continue e --resume <session-id>.

Prima della v2.1.287, Claude Code avviava l'interfaccia invece di stampare questo messaggio, quindi non mostrava nulla sullo schermo oppure falliva con un errore contenente Raw mode is not supported.

Se invece vedi Raw mode is not supported durante claude install, consulta Raw mode is not supported durante l'installazione.

L'input conteneva solo spazi vuoti

In modalità non interattiva, Claude Code rifiuta un prompt composto interamente da spazi, tabulazioni o a capo invece di inviarlo, perché l'API rifiuta i messaggi senza testo visibile. Il messaggio che vedi dipende dalla provenienza del prompt vuoto:

• Argomento del prompt o stdin tramite pipe per claude -p: claude termina con Error: Input contained only whitespace. Provide a prompt with text through stdin or as a prompt argument when using --print
• Messaggio inviato a una sessione --input-format stream-json o Agent SDK in esecuzione: Claude Code termina il turno senza chiamare il modello e la sessione resta utilizzabile. Il rifiuto arriva come messaggio informativo e come testo del risultato del turno: Blank prompt — the message was only whitespace, so nothing was sent to the model.

Prima della v2.1.229, Claude Code inviava all'API il messaggio composto solo da spazi vuoti, e l'API rifiutava la richiesta con un errore 400.

Cosa fare:

• Includi testo visibile nel prompt. Se uno script costruisce il prompt da una variabile o da un file, verifica che l'origine non sia vuota prima di chiamare Claude Code.

L'input stream-json conteneva oltre 256M caratteri senza un a capo

Il tuo programma ha inviato più di 268.435.456 caratteri su stdin senza un a capo a un'esecuzione claude -p --input-format stream-json, quindi Claude Code stampa questo errore su stderr e termina con codice di uscita 1 invece di accumulare altro input nel buffer. Il messaggio indica quel limite come 256M. Prima della v2.1.257, Claude Code accumulava tale input nel buffer senza limiti, facendo crescere la memoria finché il processo non andava in crash o veniva terminato.

Error: stream-json input carried over 256M characters with no newline. Each stream-json message must be a single newline-terminated JSON line: either the producer is not newline-terminating its messages, or one message exceeded this budget.

Un input così lungo senza un a capo di solito significa che il produttore non è affatto un produttore stream-json, come un file binario o un normale output di log inviato tramite pipe per errore. Anche un singolo messaggio che supera il limite non supera lo stesso controllo.

Cosa fare:

• Controlla cosa viene inviato tramite pipe a stdin. Con --input-format stream-json, ogni messaggio deve essere una singola riga JSON terminata da un a capo
• Per inviare invece testo semplice, rimuovi --input-format stream-json; claude -p legge per impostazione predefinita un prompt in testo semplice da stdin

Comando sconosciuto

In una sessione interattiva del terminale, hai inviato un nome / che non corrisponde ad alcun comando in questa sessione, quindi Claude Code segnala il nome invece di eseguire qualcosa:

Unknown command: /hepl. Did you mean /help?

Claude Code suggerisce il nome di comando o alias più vicino tra quelli elencati nel menu in questa sessione. Quando non c'è nulla di simile, il messaggio termina dopo il nome. La causa è di solito una delle seguenti:

• Un errore di battitura, come /hepl per /help. Come il menu dei comandi trova corrispondenze con ciò che digiti spiega come scegliere una corrispondenza vicina prima di inviare
• Un comando che esiste ma non è disponibile in questa sessione perché un requisito non è soddisfatto, come la tua piattaforma, il tuo piano o il tuo metodo di autenticazione. Le voci di risoluzione dei problemi per /web-setup e /schedule illustrano due casi comuni. Alcuni comandi rispondono con un proprio messaggio quando la policy della tua organizzazione li disabilita, come Cloud sessions are disabled by your organization's policy
• Un comando di un plugin o di un server MCP che non è installato o connesso in questa sessione

Claude Code risponde in questo modo a un nome / senza corrispondenza solo in una sessione interattiva del terminale. In tutte le altre sessioni, invia invece il prompt a Claude come un normale messaggio, con una nota che indica che il comando non è stato eseguito e un elenco dei comandi che Claude può eseguire nella sessione. Queste sessioni includono:

• Le esecuzioni con -p
• Le applicazioni Agent SDK
• La scheda Code dell'app Desktop
• Il pannello della chat dell'estensione VS Code
• Le sessioni cloud e le routine

Per un comando integrato che non può essere eseguito in una di queste sessioni, Claude Code risponde comunque che il comando non è disponibile invece di inviarlo a Claude. Prima della v2.1.274, solo le sessioni cloud e le routine inviavano a Claude un nome senza corrispondenza. Prima della v2.1.273, anche esse rispondevano con Unknown command.

Claude Code non tratta come comando ogni prompt che inizia con /. Invia il prompt a Claude come un normale messaggio quando la prima parola dopo / inizia con un segno di punteggiatura, come il /-- che apre un commento di documentazione Lean, oppure è un percorso come /var/log/syslog.

Prima della v2.1.236, se premevi Enter mentre il menu dei comandi elencava una corrispondenza vicina al nome che avevi digitato, Claude Code eseguiva quella corrispondenza, quindi un errore di battitura come /hepl eseguiva /help invece di produrre questo messaggio.

Cosa fare:

• Esegui il nome suggerito, oppure digita / seguito da parte del nome per vedere cosa è disponibile in questa sessione
• Se Claude Code segnala come sconosciuto un comando documentato, controlla la sua riga nel riferimento dei comandi per il requisito indicato

Il diff è troppo grande per ultrareview

Il diff tra il tuo branch e il branch di base, incluse le modifiche non sottoposte a commit e quelle nell'area di staging, supera i limiti di dimensione per un'ultrareview, quindi /code-review ultra e il sottocomando claude ultrareview rifiutano la revisione prima che la sessione cloud si avvii. Una revisione rifiutata non consuma un'esecuzione gratuita e non addebita crediti di utilizzo. Il messaggio indica i limiti in vigore, la dimensione del tuo diff e i file che contribuiscono con il maggior numero di righe modificate. Prima della v2.1.216, il messaggio mostrava solo le statistiche grezze del diff.

Diff is too large for ultrareview: 812 files, 96,410 lines changed (limits: 500 files, 8,000 lines). Largest files: package-lock.json (41,904 lines), dist/bundle.js (18,210 lines), src/generated/api.ts (9,876 lines). Pass a closer base branch (`/code-review ultra <branch>`) to narrow the scope, or split the change.

La revisione di una pull request applica gli stessi limiti; quella forma del messaggio inizia con PR #<N> is too large for ultrareview e indica il numero di file e di righe della PR.

Cosa fare:

• Passa un branch di base più vicino al tuo lavoro, come /code-review ultra develop, in modo che la revisione copra solo il diff rispetto a quel branch
• Suddividi la modifica in branch più piccoli e revisionali uno alla volta. I file indicati dal messaggio contribuiscono con il maggior numero di righe modificate, quindi inizia spostandoli in un branch a sé.

Impossibile trovare il merge-base con il branch di base

/code-review ultra e il sottocomando claude ultrareview revisionano il diff tra il tuo branch e un branch di base, il che richiede un commit condiviso dai due. Quando git merge-base non ne trova nessuno, Claude Code rifiuta la revisione prima che la sessione cloud si avvii. Su un clone che Claude Code può verificare come completo, con almeno un branch, ripiega sulla revisione di ogni file tracciato invece di rifiutare. Vedi questo rifiuto quando il branch di base non può essere trovato affatto, quando Claude Code non riesce a verificare che il tuo clone sia completo, oppure nel raro repository in cui il diff dell'intero albero non è possibile, come con il formato oggetti SHA-256.

Could not find merge-base with main. Pass the base branch explicitly (e.g. `/code-review ultra develop`) or make sure you're in a git repo with a main branch.

Il suggerimento dopo la prima frase dipende da ciò che Claude Code ha osservato:

• Non hai passato un branch di base: Claude Code ha effettuato il confronto con il branch predefinito del repository e suggerisce di passare esplicitamente il tuo branch di base, come nell'esempio sopra
• Hai passato un branch di base che era già nel tuo clone: il suggerimento riporta Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)
• Hai passato un branch di base che non era nel tuo clone: Claude Code ne ha eseguito il fetch da origin prima del confronto. Il suggerimento riporta <branch> was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra <branch>`); quando Claude Code non riesce a stabilire se il tuo clone è shallow, suggerisce invece git fetch --unshallow origin. Prima della v2.1.221, il suggerimento proponeva git fetch --unshallow origin per ogni branch di base recuperato, e su un clone completo quel comando fallisce con fatal: --unshallow on a complete repository does not make sense.

Cosa fare:

• Se un altro branch è il tuo vero branch di base, passalo esplicitamente: /code-review ultra <branch>
• Se il tuo clone potrebbe non avere la cronologia completa, esegui git fetch --unshallow origin ed esegui di nuovo la revisione

Il tuo checkout non ha branch

Un checkout può avere dei commit ma nessun branch: se esegui git init seguito da git fetch <url> e git checkout FETCH_HEAD, ottieni un HEAD scollegato senza ref. Claude Code impacchetta il tuo repository come bundle git per caricarlo per un'ultrareview, e non può creare il bundle di un repository che non ha branch o altri ref, quindi /code-review ultra e il sottocomando claude ultrareview rifiutano la revisione prima che la sessione cloud si avvii.

Your checkout has no branches (detached HEAD only), which cloud review can't bundle. Create one first — `git checkout -b <name>` — then rerun /code-review ultra.

Prima della v2.1.221, Claude Code tentava di revisionare ogni file tracciato in questo checkout, e il caricamento falliva.

Cosa fare:

• Crea un branch al commit corrente con git checkout -b <name>, quindi esegui di nuovo la revisione

Nessun account GitHub è collegato al tuo account Claude

Hai eseguito /code-review ultra <PR#> o claude ultrareview <PR#>, e prima di creare la sessione cloud Claude Code chiede al server se l'account GitHub collegato al tuo account Claude può accedere al repository della PR. Nessun account è collegato, o il collegamento è scaduto, quindi il clone nel cloud fallirebbe e Claude Code rifiuta l'avvio. Claude Code non consuma un'esecuzione gratuita né addebita crediti di utilizzo per un avvio rifiutato.

Ultrareview clones <owner>/<repo> in the cloud with the GitHub account connected to your Claude account, and none is connected (or the connection expired). To fix: run /web-setup to reuse your GitHub CLI login, or connect an account at https://claude.ai/connect-github — then re-run /code-review ultra 1234 (allow a minute after connecting).

Quando /web-setup non è disponibile nella tua sessione, il messaggio indica solo il link a claude.ai.

Cosa fare:

• Esegui /web-setup per collegare il tuo accesso alla GitHub CLI al tuo account Claude, oppure collega un account su claude.ai/connect-github
• Esegui di nuovo la revisione un minuto dopo il collegamento

Prima della v2.1.248, Claude Code non effettuava questo controllo prima dell'avvio.

Il tuo account GitHub collegato non può vedere il repository

Hai eseguito /code-review ultra <PR#> o claude ultrareview <PR#>, e l'account GitHub collegato al tuo account Claude non può leggere il repository della PR, quindi il clone nel cloud fallirebbe e Claude Code rifiuta l'avvio. Claude Code non consuma un'esecuzione gratuita né addebita crediti di utilizzo per un avvio rifiutato.

Your connected GitHub account can't see <owner>/<repo> — usually the Claude GitHub app isn't installed on <owner> or wasn't granted this repo (web-connected accounts need it for private repos), or a different GitHub account is connected. To fix: run /web-setup to reuse your GitHub CLI login, or install the app at https://github.com/apps/claude/installations/new — then re-run /code-review ultra 1234.

Quando /web-setup non è disponibile nella tua sessione, il messaggio indica solo l'installazione dell'app.

Cosa fare:

• Se la tua CLI gh locale può leggere il repository, esegui /web-setup per collegare quell'accesso al tuo account Claude
• Esegui di nuovo la revisione dopo la modifica

Prima della v2.1.248, Claude Code non effettuava questo controllo prima dell'avvio.

Il controllo preliminare della GitHub App non è riuscito temporaneamente

Hai avviato una sessione cloud da un repository locale, e due passaggi sono falliti insieme. Claude Code non è riuscito a creare o caricare il bundle del tuo repository. Prima del caricamento, ha verificato se il servizio cloud può clonare il repository da GitHub e, invece di una risposta definitiva, quel controllo si è concluso con un errore che un nuovo tentativo potrebbe risolvere, come un errore di rete, un timeout o un errore temporaneo del server. Il messaggio completo inizia con ciò che ha bloccato il bundle, ad esempio Could not upload repo bundle (<error>), e termina con la frase sul controllo preliminare:

Could not upload repo bundle (<error>). The GitHub App preflight failed transiently (network or service hiccup) — retry in a moment to start from GitHub instead

Cosa fare:

• Esegui di nuovo il comando dopo un momento. Quando il controllo GitHub viene superato, Claude Code può avviare la sessione da un clone GitHub, quindi il caricamento non riuscito non blocca più l'avvio
• Se i nuovi tentativi continuano a fallire, l'inizio del messaggio indica cosa ha bloccato il caricamento. Quando quella causa è qualcosa che puoi correggere, correggila in modo che la sessione possa invece avviarsi dal tuo repository locale

Prima della v2.1.251, Claude Code terminava il messaggio con Please set up GitHub on https://claude.ai/code anche quando il controllo GitHub falliva solo temporaneamente, e un consiglio di configurazione non può risolvere un errore temporaneo.

Il caricamento del repository non può seguire un'impostazione git

Hai avviato una sessione cloud che carica il tuo repository locale, oppure un'ultrareview di un branch, e il caricamento non può seguire una delle impostazioni git che determinano quali regole degli attributi si applicano ai tuoi file. Se il caricamento procedesse e ignorasse una regola, un file che git trasforma prima di memorizzarlo, come uno cifrato da un clean filter, potrebbe arrivare nel cloud così com'è su disco. Claude Code rifiuta invece il caricamento, e non viene caricato nulla:

Not uploading this working tree: core.ignoreCase (which decides whether .gitattributes patterns match file names regardless of letter case) is set in <file>, and the upload cannot follow that setting, so a file git would change before storing it (to encrypt it, for example) could be uploaded as it is on disk. Move the core.ignoreCase line into this repository’s .git/config or directly into your ~/.gitconfig, then retry.

Il messaggio indica l'impostazione e dove è impostata, e termina con la soluzione per il caso in cui ti trovi. Lo stesso rifiuto appare per core.attributesFile e attr.tree, ciascuno con la propria soluzione.

Il messaggio può indicare un file di configurazione che la tua configurazione git include tramite una direttiva include o includeIf, anche quando la condizione di quella direttiva non si applica a questo repository.

Cosa fare:

• Applica la soluzione indicata nella frase finale del messaggio

GitHub non è collegato al tuo account Claude

Hai avviato una sessione cloud dal tuo repository locale, ad esempio con /autofix-pr. Nessun account GitHub è collegato al tuo account Claude, o il collegamento è scaduto, quindi Claude Code rifiuta l'avvio:

GitHub isn't connected to your Claude account, so this repository can't be cloned in the cloud. Run /web-setup to connect with your GitHub CLI login, or connect on the web at https://claude.ai/connect-github

Quando crei una routine con /schedule, lo stesso messaggio appare come nota di configurazione che indica il repository; la nota non blocca la creazione della routine.

Cosa fare:

• Esegui /web-setup per collegare il tuo accesso alla GitHub CLI al tuo account Claude, oppure collega un account su claude.ai/connect-github. Consulta Opzioni di autenticazione GitHub per le differenze tra i due metodi.
• Esegui di nuovo il comando un minuto dopo il collegamento

Prima della v2.1.268, Claude Code segnalava questa situazione come un errore temporaneo del controllo della Claude GitHub App e suggeriva di riprovare o di installare l'app; nessuna delle due opzioni collega un account GitHub.

Una policy dell'organizzazione GitHub sta bloccando Claude

Hai eseguito al prompt di Claude Code un comando che avvia una sessione cloud, come /autofix-pr. Prima di creare la sessione, Claude Code verifica l'accesso di Claude al repository su GitHub, e GitHub lo ha rifiutato perché la tua organizzazione GitHub ha una policy che blocca Claude. Claude Code si ferma lì e mostra un messaggio che indica la policy.

Quando a bloccare l'accesso è una allowlist di IP, il messaggio è:

Your GitHub organization has an IP allowlist that is blocking Claude. Add Claude's IP ranges to your GitHub allowlist.

Quando a bloccarlo è il single sign-on, il messaggio è:

Your GitHub organization requires single sign-on. Disconnect and reconnect GitHub on the Connectors page in Claude on the web, click Authorize next to your organization when GitHub asks, then try again.

Quando a bloccarlo è una policy di accesso condizionale di Microsoft Entra ID, il messaggio è:

Your GitHub organization's identity provider (Microsoft Entra ID) has a Conditional Access policy that is blocking Claude. Ask your GitHub Enterprise or Entra ID admin to allow Claude in that policy.

Cosa fare:

• Allowlist di IP: chiedi a un proprietario della tua organizzazione o enterprise GitHub di consentire gli indirizzi IP in uscita di Anthropic. Consulta Allowlist e firewall di GitHub per gli indirizzi e le impostazioni di GitHub da modificare.
• Single sign-on: disconnetti GitHub su claude.ai/customize/connectors, quindi connettilo di nuovo. Quando GitHub lo chiede, fai clic su Authorize accanto alla tua organizzazione, in modo che la nuova connessione sia autorizzata per il suo single sign-on.
• Policy di accesso condizionale: chiedi al tuo amministratore di GitHub Enterprise o di Microsoft Entra ID di consentire Claude in quella policy
• Dopo la modifica, esegui di nuovo il comando

Autorizzazione single sign-on necessaria

Hai eseguito /install-github-app e scelto un repository la cui organizzazione impone il single sign-on SAML. Prima della configurazione, Claude Code verifica il tuo accesso al repository con la GitHub CLI, e GitHub ha rifiutato quella verifica perché il tuo token gh non è ancora autorizzato per l'organizzazione. La procedura guidata mostra l'avviso con i passaggi per l'autorizzazione:

Single sign-on authorization needed
<owner>/<repo> belongs to an organization that enforces SAML single sign-on, and your GitHub CLI token isn't authorized for it yet.

Cosa fare:

• Autorizza di nuovo il tuo accesso alla GitHub CLI con gli scope repo e workflow eseguendo gh auth refresh -h github.com -s repo,workflow, e autorizza l'organizzazione quando GitHub chiede il single sign-on
• Se ti autentichi con un personal access token in GH_TOKEN, apri github.com/settings/tokens, seleziona Configure SSO sul token e autorizza l'organizzazione
• Esegui di nuovo /install-github-app

Prima della v2.1.273, Claude Code mostrava invece l'avviso Admin permissions required per questa condizione.

Failed to resume the conversation

Claude Code non è riuscito a leggere o elaborare la trascrizione salvata della sessione che hai selezionato dal selettore di claude --resume, quindi termina il processo anziché continuare in uno stato caricato solo parzialmente. Il messaggio include il comando per riprovare:

Failed to resume the conversation.
Run claude --resume <session-id> to retry, or claude to start a new session.

Claude Code esce con codice 1 dopo aver mostrato il messaggio. Il selettore di /resume all'interno di una sessione in esecuzione segnala invece Failed to resume conversation nella conversazione, e la tua sessione corrente continua a essere eseguita. Prima della v2.1.216, una ripresa non riuscita dal selettore di claude --resume restava indefinitamente sull'indicatore Resuming conversation… invece di mostrare questo messaggio.

Cosa fare:

• Esegui claude --resume <session-id> con l'ID di sessione indicato nel messaggio per riprovare
• In una versione precedente alla v2.1.285, se il nuovo tentativo fallisce allo stesso modo, esegui claude update e riprendi di nuovo. Quelle versioni non riescono a riprendere la sessione quando la trascrizione salvata contiene una voce che non sono in grado di leggere.
• Se il nuovo tentativo fallisce ancora, esegui claude per avviare una nuova sessione

No conversation found with the session ID

Hai passato un ID di sessione a claude --resume <session-id> e nessuna trascrizione salvata corrisponde:

No conversation found with session ID: <session-id>

Claude Code esce con codice 1 dopo aver mostrato il messaggio. Claude Code cerca l'ID prima nel progetto corrente, poi in ogni altro progetto su questa macchina. Prima della v2.1.223, la ricerca si fermava alla directory del progetto corrente e ai suoi worktree git, quindi riprendi dalla directory in cui la sessione ha lavorato per ultima.

Cause comuni:

• ID digitato in modo errato: per un'esecuzione non interattiva, l'ID è il campo session_id dell'output di --output-format json
• Trascrizione eliminata: Claude Code rimuove le trascrizioni dopo il periodo di conservazione, 30 giorni per impostazione predefinita, seguendo le regole di pulizia della conservazione
• Macchina diversa: Claude Code memorizza le trascrizioni localmente, quindi riprendi la sessione sulla macchina in cui è stata eseguita
• Copie duplicate: se hai copiato una directory di progetto in ~/.claude/projects in modo che due trascrizioni abbiano lo stesso ID, Claude Code mostra questo messaggio anziché riprendere arbitrariamente una delle copie

Cosa fare:

• Per una sessione interattiva, apri il selettore delle sessioni con claude --resume e premi Ctrl+A per estenderlo a tutti i progetti su questa macchina, quindi seleziona la sessione
• Le sessioni create con claude -p o con l'Agent SDK non compaiono nel selettore, quindi ricontrolla l'ID confrontandolo con il session_id stampato dall'esecuzione originale

Windows ha segnalato un errore (EBADF) quando Claude Code ha letto il file di trascrizione di questa sessione

Hai ripreso una sessione su Windows, il suo file di trascrizione salvato si è aperto normalmente, e poi la lettura è fallita con l'errore di sistema EBADF. L'errore di sistema non indica perché la lettura sia fallita, quindi il messaggio suggerisce le cause probabili e cosa provare:

Windows reported an error (EBADF) when Claude Code read this session's transcript file, although the file had opened normally. This can happen when other software intercepts file reads — security, encryption or endpoint-management tools, for example. If it keeps happening for this conversation, try excluding the folder that holds Claude Code's session transcripts from such software (the .claude folder in your user profile, unless the app or CLAUDE_CONFIG_DIR points Claude Code elsewhere), or adding Claude Code to its allowed applications, then resume again.

Il messaggio segue la riga di errore del comando stesso, come Failed to resume session <session-id>. Un comando claude --resume o claude -p esce con codice 1 dopo averlo mostrato. Dopo /resume all'interno di una sessione, la tua sessione corrente continua a essere eseguita.

Cosa fare:

• Escludi la cartella che contiene le trascrizioni delle tue sessioni dai software che analizzano o intercettano le letture dei file, come gli strumenti di sicurezza, crittografia o gestione degli endpoint. Le trascrizioni si trovano in %USERPROFILE%\.claude\projects per impostazione predefinita, oppure nella directory indicata da CLAUDE_CONFIG_DIR
• Se non puoi aggiungere un'esclusione, aggiungi invece Claude Code alle applicazioni consentite di quel software
• Riprendi di nuovo la sessione

Prima della v2.1.282, l'errore non era accompagnato da alcuna spiegazione: claude --resume <session-id> terminava con Failed to resume session <session-id>, e un'esecuzione -p stampava solo il testo dell'errore di sistema, come Failed to resume session: EBADF: bad file descriptor, read.

Cannot switch renderers in this session

Quando cambi renderer, Claude Code riavvia il proprio processo. Hai eseguito /tui in una sessione che Claude Code si rifiuta di riavviare, quindi non effettua il cambio e non salva nulla. Il messaggio che vedi ti indica la causa:

• Cannot switch renderers while work is running in the background: hai attività in esecuzione in background che un riavvio abbandonerebbe, come una shell in background o un subagent. Attendi che l'attività finisca o interrompila con /tasks, quindi esegui di nuovo /tui fullscreen o /tui default
• Cannot switch renderers in this session: la sessione ha restrizioni che Claude Code non può passare al processo riavviato. Prima della v2.1.234, Claude Code effettuava comunque il riavvio e la sessione riavviata veniva eseguita senza di esse

Nel messaggio sulle restrizioni, la parte tra parentesi indica le restrizioni trovate da Claude Code:

Cannot switch renderers in this session — it has restrictions a restart can't carry over (permission rules set for this session only). Nothing was changed. Running /tui fullscreen in a session started without them switches every later session too.

Ogni motivo che il messaggio può mostrare tra parentesi:

• launch flags: a custom system prompt, a tool allowlist, or restricted settings: hai avviato la sessione con un flag che Claude Code non ripassa al processo riavviato. Questi flag includono --system-prompt, --system-prompt-file, --append-system-prompt-file, una allowlist --tools, --setting-sources e --permission-prompt-tool
• permission rules set for this session only: un aggiornamento dei permessi da un hook o da un chiamante SDK ha aggiunto regole deny o ask con destinazione session. Le regole allow limitate alla sessione non provocano il rifiuto. Un riavvio le elimina, e Claude Code chiede di nuovo
• ask-before-running rules with no command-line form: un aggiornamento dei permessi da un hook o da un chiamante SDK ha aggiunto regole ask insieme alle regole che Claude Code ripassa come --allowed-tools e --disallowed-tools. Non esiste alcun flag per le regole ask
• permission rules a command line cannot carry intact e added directories a command line cannot carry intact: un aggiornamento dei permessi ha aggiunto una regola o un percorso di directory durante la sessione. La riga di comando del processo riavviato non può trasportarne il testo come lo stesso valore

Cosa fare:

• In una sessione avviata senza quelle restrizioni, esegui /tui fullscreen, oppure /tui default per tornare indietro. Claude Code salva lì l'impostazione tui

Impossibile aprire Claude Desktop

Hai eseguito /desktop o il suo alias /app in una sessione, oppure claude --desktop nella tua shell, e il comando di sistema che Claude Code usa per aprire Claude Desktop non è riuscito. Dopo /desktop, la sessione resta nel terminale; claude --desktop stampa il messaggio senza il prefisso Error: ed esce con stato 1.

Il testo tra parentesi indica il comando non riuscito, con il suo stato di uscita e la prima riga del suo output di errore quando li ha prodotti. Su macOS quel comando è open, come in questo esempio; su Windows è rundll32:

Error: Couldn't open Claude Desktop (`open` exited 1: LSOpenURLsWithRole() failed for the URL claude://resume?session=<session-id> with error -10814). Open Claude Desktop and try again.

Cosa fare:

• Apri Claude Desktop manualmente, quindi esegui di nuovo /desktop o claude --desktop
• Per leggere l'output di errore completo del comando non riuscito, attiva il logging di debug con /debug ed esegui di nuovo /desktop, oppure esegui claude --desktop --debug-file <path>, quindi controlla il log di debug

Prima della v2.1.285, il messaggio terminava con Open Claude Desktop and run /desktop again. Prima della v2.1.275, era Failed to open Claude Desktop. Please try opening it manually. e non indicava cosa fosse fallito.

/terminal-setup ha lasciato invariata la tua keymap di Zed

Hai eseguito /terminal-setup in Zed, e Claude Code non è riuscito a completare l'aggiornamento del tuo keymap.json di Zed, quindi ha lasciato il file com'era.

Ogni messaggio indica il percorso della tua keymap e termina con il blocco della scorciatoia da tastiera da aggiungere manualmente:

Couldn't update your Zed keymap, so it was left unchanged.
To add the binding yourself, add this block to the keymap array in <path to keymap.json>:
{ "context": "Terminal", "bindings": { "shift-enter": ["terminal::SendText", "\u001b\r"] } }

La prima riga del messaggio indica la causa:

• Couldn't read your Zed keymap, so it was left unchanged.: Claude Code non è riuscito a leggere il file, ad esempio a causa dei permessi sui file
• Your Zed keymap isn't a readable list of keybindings, so it was left unchanged.: il file è stato letto correttamente ma non viene interpretato come un array di blocchi di scorciatoie da tastiera, nemmeno consentendo commenti // e virgole finali
• Couldn't back up your Zed keymap; not modifying it.: Claude Code non è riuscito a copiare il file in un backup .bak accanto a esso, quindi non ha modificato nulla
• Couldn't update your Zed keymap, so it was left unchanged.: il risultato dell'unione non è stato verificato come keymap valida contenente la scorciatoia, quindi Claude Code lo ha scartato invece di scriverlo. Un blocco di scorciatoie da tastiera con una chiave duplicata può causare questo problema

Cosa fare:

• Copia il blocco dal messaggio nell'array di primo livello del tuo keymap.json al percorso indicato dal messaggio
• Per isn't a readable list of keybindings, correggi l'errore di sintassi, oppure rendi un array il valore di primo livello del file, quindi esegui di nuovo /terminal-setup

Prima della v2.1.247, /terminal-setup non riusciva a interpretare una keymap di Zed che usava commenti // o virgole finali, e sostituiva l'intero file con la sola propria scorciatoia, segnalando comunque la scorciatoia come installata. Per ripristinare una keymap sostituita da una versione precedente, usa il file di backup .bak descritto in Inserire prompt su più righe.

Skill usage reports are not available on this connection

Hai eseguito /skill-doctor tramite Remote Control, dal telefono o dal browser. Claude Code non invia il report sull'utilizzo delle skill tramite Remote Control e risponde invece con questo messaggio:

Skill usage reports are not available on this connection.

Cosa fare:

• Esegui /skill-doctor nel terminale della macchina su cui è in esecuzione la sessione, oppure esegui lì claude -p "/skill-doctor"

Gli stili di output personalizzati non possono essere selezionati tramite Remote Control

Hai eseguito /output-style dall'app mobile o dal web tramite Remote Control, oppure il comando è arrivato in un messaggio inoltrato nella sessione. Poiché un turno di questo tipo potrebbe non provenire dal proprietario dell'account, Claude Code elenca e seleziona in esso solo gli stili integrati, e aggiunge questo avviso ogni volta che il comando elenca gli stili o non riconosce il nome che hai fornito. Il nome di uno stile personalizzato riceve la stessa risposta di un nome che non esiste:

Custom output styles can't be selected over Remote Control or from a relayed message. Select one in the session itself, or pick a built-in style here.

Cosa fare:

• Scegli uno stile integrato, ad esempio /output-style concise
• Per usare uno stile personalizzato, imposta outputStyle nel file .claude/settings.local.json del progetto, oppure esegui /output-style <style> nel terminale della sessione stessa, se ne ha uno

Gli stili di output vengono salvati nelle impostazioni locali, che questa sessione non carica

Hai provato a cambiare stile di output con /output-style <style> o /config outputStyle=<style> in una sessione le cui origini delle impostazioni escludono local. Esempi sono una sessione dell'Agent SDK il cui settingSources non include "local" e una sessione della CLI avviata con un valore di --setting-sources che non include local. Entrambi i comandi salvano lo stile in .claude/settings.local.json, un file che una sessione di questo tipo non rilegge mai, quindi Claude Code rifiuta anziché scrivere un'impostazione che non avrebbe alcun effetto:

Output styles are saved to local settings (.claude/settings.local.json), which this session doesn't load, so the style can't be changed here.

Cosa fare:

• Aggiungi local alle origini delle impostazioni della sessione e cambia di nuovo stile
• Imposta la chiave outputStyle in un file di impostazioni che la sessione carica, come .claude/settings.json nel progetto o ~/.claude/settings.json. Nell'SDK TypeScript, imposta invece outputStyle all'interno dell'oggetto inline settings; consulta Attivare uno stile di output

/recap viene eseguito solo quando lo richiedi tu stesso

La richiesta /recap non proviene dal tuo input. È arrivata in un messaggio inoltrato nella sessione da un thread di Slack, Teams o di un progetto, oppure in un prompt inviato da una routine o da un altro programma.

Un messaggio inoltrato riceve l'avviso anche se l'hai scritto tu. Claude Code non può stabilire che un messaggio inoltrato o automatizzato provenga dalla persona con il cui account è in esecuzione la sessione, quindi risponde con questo avviso invece che con un riepilogo:

/recap only runs when you ask for it yourself in this session: from the terminal, the Claude app or claude.ai/code, or over Remote Control. A message relayed from Slack, Teams or a project thread, or sent by a routine or another program, can't request it.

Un /recap che passi a claude -p, o che la tua applicazione Agent SDK invia a una sessione che ha avviato, conta come tuo input.

Cosa fare:

• Apri tu stesso la sessione ed esegui lì /recap: nel suo terminale, nell'app Desktop o nell'app mobile, su claude.ai/code, oppure tramite Remote Control
• Se l'ha inviato una routine o un altro programma, rimuovi /recap da quel prompt

Errori dei plugin

Questi errori provengono dalla configurazione di plugin e marketplace. Per i problemi dei plugin che non producono uno dei messaggi in questa pagina, come un URL del marketplace che non si carica o un plugin che si installa ma non appare, vedi Risoluzione dei problemi dei plugin.

plugin eval è attualmente in accesso anticipato

Hai eseguito claude plugin eval o claude plugin eval init e ha terminato con codice 1 con uno di questi messaggi prima di fare qualsiasi cosa:

`plugin eval` is currently in early access

`plugin eval` is currently unavailable

Il primo messaggio significa che la tua build è più vecchia della v2.1.269, la prima versione in cui il comando è generalmente disponibile. Il secondo significa che Anthropic ha disattivato il comando lato server; nulla sulla tua macchina lo riattiva.

Cosa fare:

• Esegui claude --version, quindi claude update, ed esegui il comando di nuovo in una nuova sessione. Vedi i requisiti per le valutazioni dei plugin
• Se vedi il secondo messaggio su una build attuale, riprova più tardi dopo un altro claude update

Marketplace è registrato da una fonte non attendibile

Il marketplace è registrato con un nome che è riservato per i marketplace ufficiali di Anthropic, ma la sua fonte registrata non è un repository GitHub anthropics. Claude Code ri-controlla i nomi riservati ogni volta che carica o aggiorna un marketplace, quindi il marketplace e i plugin installati da esso smettono di caricarsi. Prima della v2.1.205, una voce registrata prima che il suo nome diventasse riservato continuava a caricarsi.

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.

Per un marketplace la cui fonte non è un repository GitHub o un URL Git, come una directory locale, la frase centrale legge can only be used with GitHub sources from the 'anthropics' organization invece. claude plugin marketplace add esegue lo stesso controllo e rifiuta un nome riservato con Failed to add marketplace: seguito dalla stessa frase del nome riservato.

Cosa fare:

• Se il marketplace è già registrato, esegui claude plugin marketplace remove <name>, quindi aggiungilo di nuovo dal repository ufficiale github.com/anthropics
• Se pubblichi un marketplace di terze parti che ha utilizzato il nome prima che diventasse riservato, rinominalo e chiedi agli utenti di aggiungerlo di nuovo dalla tua fonte
• Vedi l'elenco dei nomi riservati in Schema del Marketplace

Il nome del marketplace è un'altra ortografia di un nome riservato

Il nome del marketplace non è di per sé un nome riservato, ma Claude Code lo tratta come un'altra ortografia di uno. Nomi riservati elenca quali ortografie contano come un nome riservato. Claude Code rifiuta un tale nome quando aggiungi il marketplace:

Failed to add marketplace: "claude.code.plugins" is another spelling of "claude-code-plugins", a reserved marketplace name.

Quando un marketplace è già registrato con un tale nome, la sua voce smette di caricarsi, e /plugin, claude plugin install, e claude plugin update avvertono:

known_marketplaces.json has an entry named "claude.code.plugins", another spelling of the reserved marketplace name "claude-code-plugins", so it is ignored. Remove it with: claude plugin marketplace remove claude.code.plugins

Quando il nome avrebbe bisogno di quoting della shell, il rifiuto al momento dell'aggiunta legge This marketplace's name is another spelling of "<reserved>", a reserved marketplace name. It is not exactly the reserved name it appears to be.

Cosa fare:

• Rinomina il marketplace con un nome che non ortografia un nome riservato e aggiungilo di nuovo
• Per l'avvertimento della voce ignorata, esegui il comando claude plugin marketplace remove che fornisce, o rimuovi la voce da ~/.claude/plugins/known_marketplaces.json

Claude Code rifiuta il nome del marketplace

Il nome di un marketplace registrato impersona un marketplace ufficiale di Anthropic secondo le regole che quella sezione elenca.

Se un marketplace è stato registrato con un tale nome prima che il controllo lo bloccasse, il marketplace e i plugin installati da esso smettono di caricarsi, perché Claude Code controlla il nome ogni volta che legge il catalogo del marketplace. Quando il nome imita uno ufficiale, claude plugin list e la scheda Errors di /plugin segnalano ogni plugin interessato con un messaggio che inizia:

Claude Code refuses the marketplace name "anthropic-plugins-v2"

Per un nome che imita, l'errore del marketplace stesso legge Claude Code refuses this marketplace's name: it looks like one of Anthropic's own invece. claude plugin marketplace add rifiuta qualsiasi nome che impersona con Marketplace name impersonates an official Anthropic/Claude marketplace.

Prima della v2.1.282, claude plugin list e /plugin segnalano i plugin di un nome che imita come non riusciti a caricarsi anche, senza nominare il nome del marketplace come la causa.

Cosa fare:

• Esegui claude plugin marketplace remove <name>. Questo disinstalla anche i plugin installati dal marketplace e cancella i loro dati salvati
• Per mantenere il marketplace invece, attendi fino a quando il suo manutentore lo rinomina, quindi esegui claude plugin marketplace update <name>
• Se pubblichi il marketplace, rinominalo nel tuo marketplace.json; gli utenti aggiornano il marketplace invece di rimuoverlo

Marketplace è già aggiunto da una fonte diversa

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

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.

Cosa fare:

• Se il marketplace che hai già aggiunto è quello che desideri, installa da esso per nome: /plugin install <plugin>@<name>
• Per passare alla nuova fonte, esegui /plugin marketplace remove <name>, quindi riprova l'installazione

Il comando del plugin fa riferimento a user\_config in un comando shell

Un hook del plugin, monitor, o comando MCP headersHelper fa riferimento a un'opzione del plugin ${user_config.KEY}, e la stringa sostituita verrebbe passata a una shell. Un valore configurato contenente $(...), backtick, o ; verrebbe eseguito come codice lì, quindi Claude Code rifiuta di avviare il componente invece di sostituire il valore. Il controllo viene eseguito sul modello di comando, quindi l'errore appare anche quando nessun valore è ancora configurato. Prima della v2.1.207, il valore veniva sostituito nel comando shell.

La formulazione dipende da quale superficie ha fatto riferimento all'opzione. Un hook in forma shell segnala:

Hook from plugin formatter@acme-tools references ${user_config.*} in a shell-form command. The substituted value would be re-parsed by the shell. Use exec form instead — {"command": "<executable>", "args": ["${user_config.KEY}", ...]} — or read $CLAUDE_PLUGIN_OPTION_<KEY> from the hook's environment. Command: ./scripts/notify.sh ${user_config.webhook_url}

Un monitor segnala:

Monitor "deploy-status" from plugin deploy-tools references ${user_config.*} in its command. The substituted value would be passed to a shell. Monitor commands cannot safely reference ${user_config.*}; have the monitor script read the value from a config file or prompt instead.

Un MCP headersHelper segnala:

headersHelper for MCP server 'internal-api' references ${user_config.*}. The substituted value would be passed to a shell; read the value inside the helper script instead (e.g. from an env var set in the server's "env" block).

Cosa fare:

• Per un hook, aggiungi un array args in modo che venga eseguito in forma exec, dove ogni ${user_config.KEY} diventa un argomento senza shell in mezzo. Oppure elimina il riferimento e leggi la variabile di ambiente $CLAUDE_PLUGIN_OPTION_<KEY> all'interno dello script
• Per un monitor, elimina il riferimento e fai leggere al monitor script il valore da un file di configurazione
• Per un headersHelper, sposta ${user_config.KEY} nel campo headers del server, che non viene analizzato dalla shell, o leggi il valore all'interno dello script helper

Controllo dell'integrità dell'archivio del plugin non riuscito

La voce del marketplace del plugin utilizza una fonte archive con un pin sha256, e il digest del file scaricato non corrisponde al pin. Claude Code rifiuta l'installazione, quindi nulla cambia nella cache del plugin. La mancata corrispondenza ha tre possibili cause:

• Il file all'URL è cambiato dopo che l'autore ha calcolato il pin
• L'autore ha inserito il digest sbagliato nella voce del marketplace
• L'URL serve un file diverso da quello che l'autore ha pinato

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.

Cosa fare:

• Se pubblichi il plugin, ricalcola il digest del file esatto che l'URL serve, ad esempio con shasum -a 256 my-plugin.zip, o Get-FileHash -Algorithm SHA256 my-plugin.zip in PowerShell, e aggiorna sha256 nella voce del marketplace
• Se installi il plugin, esegui /plugin marketplace update <name> 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 un aggiornamento, chiedi al proprietario del marketplace quale file hanno pinato prima di installare

Il percorso esce dalla directory del plugin

Un percorso del componente del plugin, dichiarato nel plugin.json del plugin o nella sua voce del marketplace, si risolve al di fuori della directory del plugin. Claude Code elimina quel percorso e carica il resto del plugin. Il nome del componente nel messaggio, come commands o hooks, nomina il campo che ha dichiarato il percorso.

commands path escapes plugin directory: ./../shared.md

Nell'output del comando claude plugin, lo stesso errore legge Path escapes plugin directory: ./../shared.md (commands).

Claude Code rifiuta sia un percorso che punta al di fuori del plugin come scritto, come ../shared-utils, sia un symlink che porta al di fuori del plugin e non è uno che le regole del symlink del marketplace consentono. Per un symlink, il messaggio dice anche dove il percorso si risolve:

commands path escapes plugin directory: ./commands/deploy.md — it resolves to /home/user/shared/deploy.md, outside the plugin directory

Su macOS e Linux, Claude Code rifiuta anche un percorso del componente che contiene una barra rovesciata ovunque in esso, anche quando il percorso rimane all'interno del plugin. Un plugin i cui percorsi dei componenti utilizzano separatori in stile Windows si carica su Windows e attiva questo rifiuto sulle altre piattaforme:

commands path escapes plugin directory: ./commands\deploy.md — its path contains a backslash, which is not resolved reliably on this platform

Prima della v2.1.251, Claude Code caricava un percorso commands dichiarato in una voce del marketplace anche quando puntava al di fuori della directory del plugin.

Prima della v2.1.257, il controllo guardava solo l'ortografia del percorso, non dove un symlink porta.

Cosa fare:

• Sposta il file referenziato all'interno della directory del plugin e punta il percorso ad esso con un percorso relativo ./
• Se il percorso è un symlink a un file al di fuori del plugin, sostituisci il symlink con una copia del file
• Se il messaggio dice che il percorso contiene una barra rovesciata, scrivi il percorso con barre in avanti, ad esempio ./commands/deploy.md
• Per condividere file con altri plugin nello stesso marketplace, collegali con un symlink all'interno della directory del plugin, seguendo le regole del symlink

Il percorso non poteva essere controllato

Claude Code ha chiesto al sistema operativo se un percorso del plugin esiste e ha ricevuto un errore diverso da "non trovato", quindi non carica ciò che il percorso nomina. Quanto del plugin si carica dipende da quale percorso ha fallito:

• Una delle posizioni dei componenti predefiniti di un plugin, come la cartella skills/, il file monitors/monitors.json, o uno SKILL.md alla radice del plugin: gli altri componenti del plugin si caricano ancora
• La directory del plugin stesso: nulla da quel plugin si carica

Non vedi questo errore per un percorso che non esiste affatto. In /plugin, l'errore appare sotto il plugin e nomina il percorso e il codice che il sistema operativo ha restituito:

skills path could not be checked: /home/user/my-plugin/skills (ELOOP)

In claude plugin list, lo stesso errore legge Path not found: /home/user/my-plugin/skills (skills, ELOOP).

Le cause che producono questo errore includono:

• ELOOP: un symlink nel percorso punta a se stesso o forma un ciclo
• EIO o ESTALE: il percorso è su un mount di rete che è rotto o stantio
• EACCES: una delle directory sopra il percorso nega il permesso di attraversarla

Cosa fare:

• Sostituisci un symlink che punta a se stesso con una cartella reale, o eliminalo
• Se il percorso è su un mount di rete, rimonta la condivisione
• Se il codice è EACCES, ripristina il tuo permesso di esecuzione sulle directory sopra il percorso
• Esegui /reload-plugins dopo aver corretto il percorso, o riavvia Claude Code, per caricare il plugin o il componente

Prima della v2.1.265, Claude Code trattava una cartella del componente predefinito che non poteva controllare come assente e caricava il plugin senza quel componente, senza errore.

Il percorso della voce del marketplace non rimane all'interno della directory del marketplace

La voce del marketplace del plugin dichiara un percorso di origine che Claude Code non può risolvere a una posizione all'interno della directory del marketplace stesso, quindi il plugin non si installa o carica. Il rifiuto copre:

• Un percorso della voce che è assoluto, sale fuori dal marketplace con .., o è scritto come un percorso di rete
• Su macOS e Linux, un percorso della voce che contiene una barra rovesciata ovunque dopo il ./ iniziale
• Una voce in un marketplace recuperato da una fonte remota, come git o un URL, che raggiunge il suo target attraverso un symlink che si risolve al di fuori della directory del marketplace
• Una voce relativa in un marketplace aggiunto da un URL diretto al suo marketplace.json: Claude Code scarica solo quel file, quindi nessun file di plugin locale esiste per il percorso da nominare. Vedi I plugin con percorsi relativi falliscono nei marketplace basati su URL

claude plugin install segnala il rifiuto così:

Cannot install my-plugin@my-marketplace: its marketplace entry path does not stay inside the marketplace directory (an absolute, climbing, network-shaped, backslash-containing or link-traversing entry, an entry of a fetched marketplace that resolves or opens outside its tree — or a relative entry in a url-catalog marketplace, which has no local directory)

Quando il percorso di una voce di un plugin già installato fallisce lo stesso controllo, claude plugin list mostra il plugin come failed to load con:

Plugin source path refused: ./my-plugin does not stay inside its marketplace directory. Check that the marketplace entry has a plain relative path.

Cosa fare:

• Se mantieni il marketplace, scrivi il source della voce come un percorso relativo semplice con barre in avanti, come ./plugins/my-plugin, e mantieni qualsiasi symlink che attraversa puntato all'interno della directory del marketplace
• Se hai aggiunto il marketplace da un URL diretto, le voci relative non possono risolversi. Chiedi all'autore del marketplace di utilizzare un'altra fonte di plugin, o aggiungi il marketplace dal suo repository git invece

Impossibile caricare la configurazione del marketplace

Claude Code mantiene i marketplace dei plugin che hai aggiunto in un file di registro in ~/.claude/plugins/known_marketplaces.json. Un comando di plugin che ha bisogno del registro, come claude plugin install, fallisce con uno di due messaggi quando Claude Code non può utilizzare il file:

• Failed to load marketplace configuration: il file esiste ma non è JSON valido o non può essere letto. Un file vuoto fallisce in questo modo anche.
• Marketplace configuration file is corrupted: il file è JSON valido ma i suoi contenuti non corrispondono allo schema del registro.

Con un file vuoto, claude plugin install segnala:

✘ Failed to install plugin "my-plugin": Failed to load marketplace configuration: JSON Parse error: Unexpected EOF

Prima della v2.1.246, claude plugin install non segnalava questo fallimento.

Cosa fare:

• Apri ~/.claude/plugins/known_marketplaces.json e ripara il JSON, o correggi le voci che il messaggio nomina come non corrispondenti allo schema del registro
• Se non puoi ripararla, elimina il file o sostituisci i suoi contenuti con {}, quindi aggiungi di nuovo ogni marketplace con claude plugin marketplace add <source>. Claude Code ri-registra i marketplace che le tue impostazioni utente o gestite dichiarano in extraKnownMarketplaces la prossima volta che lo avvii in una cartella che hai fiducia.

Il plugin è richiesto dalla tua organizzazione

Hai eseguito claude plugin disable, o utilizzato la scheda Installed di /plugin, per disattivare un plugin sincronizzato da claude.ai che la tua organizzazione contrassegna come richiesto:

Plugin "<name>@synced" is required by your organization and can't be disabled here. Contact your admin to change it.

Claude Code non salva nulla e il plugin rimane abilitato.

Quando provi a disabilitare un plugin da cui dipende un plugin richiesto, Claude Code rifiuta allo stesso modo, con un messaggio che nomina il plugin richiesto che lo necessita.

Cosa fare:

• Chiedi a un amministratore della tua organizzazione claude.ai di cambiare lo stato richiesto del plugin su claude.ai

Il plugin non è stato disinstallato

Hai eseguito claude plugin uninstall, o scelto Uninstall nella scheda Installed di /plugin, e la disinstallazione si è fermata con un messaggio che inizia "<plugin>" was not uninstalled:. Se il testo dopo i due punti inizia con installed_plugins.json invece di nominare un file di impostazioni, la causa è il contenuto in installed_plugins.json che questa versione di Claude Code non può leggere. Per quella forma, vedi installed_plugins.json contiene un record che questa versione non può leggere.

Quando Claude Code ha rimosso la voce del plugin da enabledPlugins e ha letto i file di impostazioni di quel scope di nuovo, o il plugin era ancora acceso lì, o un file che potrebbe accenderlo non poteva essere letto o controllato. Eliminare le opzioni salvate del plugin, i segreti e i dati mentre una voce di impostazioni potrebbe accenderlo di nuovo perderebbe, quindi la disinstallazione si ferma invece: il plugin rimane installato e nulla che ha salvato viene eliminato.

✘ Failed to uninstall plugin "formatter": "formatter" was not uninstalled: it is still switched on in /home/user/project/.claude/settings.local.json, although the settings change reported no error. It is still installed. Take it out of "enabledPlugins" in that file yourself, then uninstall it again.

Il mezzo del messaggio nomina il file e la causa:

• it is still switched on in <file>, although the settings change reported no error: la scrittura delle impostazioni ha segnalato il successo ma la voce è ancora lì quando il file viene letto di nuovo
• it is still switched on in <file>, and the settings change failed (<error>): il file non poteva essere salvato, per il motivo tra parentesi
• <file> is there and could not be read: il file esiste ma non poteva essere letto come impostazioni, ad esempio perché non è JSON valido, quindi potrebbe ancora abilitare il plugin
• <file> (not read: it is on a network path or is a link to one, or could not be checked): Claude Code non ha letto il file di impostazioni del progetto o locale perché il file, o la cartella .claude che lo contiene, è un link che porta a una posizione di rete, o perché non poteva esaminare quel percorso

claude plugin uninstall esce con 1, e con --json il risultato porta failureCode: "settings_still_on". /plugin mostra lo stesso messaggio.

Cosa fare:

• Segui l'ultima frase del messaggio: ripara o sostituisci il file di impostazioni che nomina, o rimuovi la voce del plugin da enabledPlugins in quel file tu stesso, quindi esegui di nuovo la disinstallazione

Errori degli strumenti

Questi errori provengono dalle chiamate agli strumenti di Claude. Claude corregge la maggior parte degli errori degli strumenti autonomamente. Quando uno richiede una modifica da parte tua, l'elenco Cosa fare di quell'errore specifica cosa cambiare.

No such tool available

Claude ha chiamato uno strumento con un nome che non è nell'elenco degli strumenti della sessione. Claude Code restituisce l'errore a Claude come risultato della chiamata allo strumento, e il turno continua. Quando Claude Code riesce a capire perché lo strumento manca, aggiunge una frase dopo il nome dello strumento che indica il motivo o nomina lo strumento da chiamare al suo posto, come nella seconda riga:

Error: No such tool available: <tool name>
Error: No such tool available: read. Tool names are case-sensitive: call Read instead.

Subito dopo che riprendi una sessione, un server MCP può essere ancora al suo primo tentativo di connessione quando Claude chiama uno dei suoi strumenti. Claude Code allora attende il server e restituisce questo errore se lo strumento non è ancora disponibile al termine dell'attesa. Prima della v2.1.284, una chiamata di questo tipo falliva immediatamente invece di attendere.

Anche una chiamata il cui nome dello strumento Claude Code ha troncato a 200 caratteri fallisce con questo errore.

Cosa fare:

• Se succede una volta, non devi fare nulla. Claude legge l'errore e il turno continua.
• Se le chiamate agli strumenti di un server MCP continuano a fallire con questo errore, esegui /mcp nella sessione o claude mcp list nella tua shell per controllare lo stato del server, e riconnetti un server non riuscito da /mcp. Nell'Agent SDK, consulta Gestione degli errori.

Agent would be spawned with zero tools

Ogni voce nell'elenco tools del subagent non ha corrisposto a uno strumento utilizzabile, quindi Claude Code ha rifiutato di avviare il subagent: senza strumenti, non poteva agire. Il messaggio raggruppa le tue voci in base a cosa è andato storto:

• Unrecognized: la voce non corrisponde a nessun nome di strumento, di solito un errore di battitura come Grpe per Grep.
• Not available to subagents: la voce nomina uno strumento reale che i subagent non possono usare. I subagent in background mantengono un set di strumenti integrati più piccolo, quindi una voce che solo un subagent in foreground può usare finisce qui quando il subagent verrebbe eseguito in background, che è l'impostazione predefinita. Se elenchi Agent, il messaggio lo segnala invece nel gruppo successivo.
• Matched no tools in this session: la voce è valida ma nessuno strumento nella sessione corrente vi corrisponde in questo momento, come mcp__github__* senza alcun server MCP GitHub connesso, o Agent per un subagent al limite di profondità.

Omettere il campo tools non attiva mai questo rifiuto. Se lasci l'elenco tools vuoto, o disallowedTools rimuove ogni voce in esso, Claude Code salta anche il rifiuto e avvia il subagent senza strumenti.

Prima della v2.1.208, il subagent veniva avviato senza strumenti e poteva restituire un risultato vuoto o confuso.

Agent 'code-reviewer' would be spawned with zero tools — refusing. Its tools list resolved to nothing: unrecognized [Grpe]. Fix the agent's tools frontmatter or pass a different subagent_type.

Cosa fare:

• Correggi ogni voce che l'errore nomina confrontandola con gli strumenti disponibili per i subagent
• Rimuovi le voci per gli strumenti che la sessione non ha, come gli strumenti MCP di un server che non è connesso
• Per uno strumento che i subagent in background eliminano, come CronCreate, rimuovi la voce. Per mantenere lo strumento, disattiva la fork mode e chiedi a Claude di eseguire il subagent in foreground
• Elimina il campo tools invece di elencare gli strumenti per dare al subagent ogni strumento disponibile per i subagent
• Per un elenco tools che contiene solo Agent, aumenta il limite di profondità o dai all'agente almeno un altro strumento: Claude Code trattiene Agent a quel limite, quindi un elenco senza nient'altro si risolve in nessuno strumento

File is covered by a Read deny rule

Lo strumento Edit o Write è stato chiamato su un percorso corrispondente a una regola di negazione Read, inclusa la creazione di un nuovo file in quel percorso. Entrambi gli strumenti modificano contenuto che Claude deve essere in grado di rileggere, quindi Claude Code rifiuta la chiamata prima di qualsiasi accesso ai file. NotebookEdit non è coperto dalle regole di negazione Read. Prima della v2.1.228, la regola bloccava solo lo strumento Edit, e prima della v2.1.208, solo una regola di negazione Edit bloccava le modifiche.

File is covered by a Read deny rule in your permission settings and cannot be edited.

Quando Claude Code rifiuta lo strumento Write, il messaggio termina invece con and cannot be written.

Cosa fare:

• Se Claude dovrebbe essere in grado di modificare il file, rimuovi o restringi la regola di negazione Read in /permissions o nelle impostazioni
• Se il file deve rimanere intatto, mantieni la regola e aggiungi una regola di negazione Edit per lo stesso percorso per bloccare anche lo strumento NotebookEdit

Path cannot contain null bytes

L'argomento di percorso o pattern di una chiamata a uno strumento per i file conteneva un byte null, che i file system e gli strumenti di ricerca non possono accettare. Read, Write, Edit, NotebookEdit, Glob e Grep effettuano questo controllo, e il messaggio nomina lo strumento e l'argomento:

Read file_path cannot contain null bytes (\0). Remove the null byte and try again.

La chiamata allo strumento fallisce, Claude vede l'errore, e il turno continua.

Cosa fare:

• Niente da parte tua: l'errore viene restituito a Claude come risultato dello strumento, e il messaggio stesso dice a Claude di rimuovere il byte null e riprovare

Prima della v2.1.281, un byte null in un percorso di Read, Write, Edit o NotebookEdit terminava l'intero turno con un errore che nominava Path contains null bytes, e lo strumento non veniva mai eseguito.

subagent\_type is required

subagent_type is required: the general-purpose agent is not available in this session. Available agents: ...

Claude ha chiamato lo strumento Agent senza un subagent_type, e questa sessione non ha un subagent general-purpose su cui ripiegare. Questo accade in due configurazioni:

• CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 è impostato in modalità non interattiva, il che rimuove ogni subagent integrato
• L'agente del thread principale della sessione ha un'allowlist tools: Agent(...) che esclude general-purpose

Cosa fare:

• Di solito niente: il messaggio elenca i subagent che la sessione ha, quindi Claude può riprovare con uno di essi
• Se Claude continua a fallire, aggiungi general-purpose all'allowlist tools: Agent(...), o rimuovi l'impostazione di CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS

Prima della v2.1.235, la stessa chiamata falliva con Agent type 'general-purpose' not found.

Memory index is over its read limit

Claude ha scritto nell'indice della memoria automatica MEMORY.md e l'ha lasciato oltre uno dei suoi limiti di lettura: 200 righe o 25KB. La scrittura è riuscita, ma solo le prime 200 righe o 25KB, a seconda di quale limite viene raggiunto per primo, vengono caricate all'inizio di una sessione, quindi tutto ciò che supera il limite viene scartato ogni volta che l'indice viene letto. Prima della v2.1.210, un indice oltre il limite veniva silenziosamente troncato al caricamento successivo senza alcun segnale al momento della scrittura.

Error: this write left the memory index at MEMORY.md at 214 lines, over its 200-line read limit. The write succeeded, but everything past the limit is silently dropped each time the index is loaded — entries at the end are already invisible to readers. Rewrite it to under 140 lines now: keep one line per entry, move detail into topic files, and merge or drop stale entries.

Solo il contenuto che viene caricato conta ai fini dei limiti. Il frontmatter YAML e i commenti HTML a livello di blocco vengono rimossi prima che l'indice venga caricato, quindi sono esclusi dalla misurazione. Prima della v2.1.211, Claude Code misurava il file grezzo, e il frontmatter o i commenti potevano attivare questo errore anche quando il contenuto caricato rientrava nei limiti.

Claude Code consegna l'errore a Claude dopo la scrittura invece di stamparlo come banner nel tuo terminale, quindi potresti notarlo solo nella trascrizione.

Quando la scrittura di Claude porta il file vicino a un limite senza superarlo, Claude Code restituisce un promemoria più blando per compattare l'indice invece di questo errore.

Cosa fare:

• Lascia che Claude riscriva MEMORY.md, o chiediglielo: mantenere una riga per voce, spostare i dettagli nei file di argomento, e fare il merge delle voci obsolete o eliminarle
• Per ridurre l'indice tu stesso, consulta Audit and edit your memory

pkill pattern matches the Claude Code process

Un comando pkill in una chiamata allo strumento Bash ha usato un pattern, tipicamente con -f, che corrisponde al processo stesso di Claude Code, quindi Claude Code rifiuta il comando invece di lasciare che termini la sessione. Claude Code testa il pattern con pgrep prima di eseguire pkill e rifiuta quando il proprio ID di processo è nel risultato. Il controllo viene eseguito solo su Linux; su macOS, pkill viene eseguito senza modifiche. Prima della v2.1.214, il comando veniva eseguito, e un pattern corrispondente terminava la sessione di Claude Code a metà turno.

pkill: refusing to run — this pattern matches the Claude CLI process (PID 12345). Narrow the pattern, or target your own children with `pkill -P $$ ...`.

Il rifiuto appare nel risultato dello strumento Bash invece che come banner nel tuo terminale, e Claude di solito corregge il comando autonomamente.

Cosa fare:

• Restringi il pattern in modo che corrisponda solo al processo previsto, ad esempio il percorso completo del binario di destinazione invece di una breve sottostringa
• Per interrompere i processi avviati dalla shell corrente, usa pkill -P $$ con il pattern, che limita la corrispondenza ai processi figli della shell stessa

Failed to write to a teammate's inbox

Claude Code non è riuscito a scrivere un messaggio nel file della casella di posta di un compagno di squadra in ~/.claude/teams/{team-name}/inboxes/, quindi il destinatario non ha ricevuto nulla. La scrittura fallisce quando Claude Code non può creare o aggiornare il file, ad esempio perché il disco è pieno, la directory non è scrivibile, o un altro agente mantiene il blocco della casella di posta troppo a lungo. Prima della v2.1.224, Claude Code segnalava il messaggio come inviato anche quando la scrittura falliva.

L'errore appare nel risultato dello strumento dell'agente mittente invece che come banner nel tuo terminale, e il suo testo dice a Claude di riprovare:

Failed to write to researcher's inbox — nothing was sent. Try again, or message the lead.

I messaggi strutturati del protocollo del team di agenti falliscono allo stesso modo, e l'errore nomina il messaggio non consegnato: quando Claude Code non riesce a scrivere un'approvazione del piano, un rifiuto del piano, una richiesta di arresto o un rifiuto di arresto, l'errore riporta Failed to write the <message> to <name>'s inbox — nothing was sent. Il plan approval in quell'elenco è la decisione del lead che approva il piano di un compagno di squadra; l'invio del piano da parte del compagno di squadra è il messaggio separato plan approval request. Quel messaggio e altri due messaggi del protocollo hanno un proprio testo e una propria conseguenza:

• Failed to write the plan approval request to the lead's inbox — plan not submitted; try again: il piano del compagno di squadra non ha mai raggiunto il lead, e il compagno di squadra rimane in plan mode finché un nuovo invio non riesce
• The permission request could not be delivered to the team lead (mailbox write failed): la richiesta di permesso del compagno di squadra non ha mai raggiunto il lead, quindi nessuno ha approvato la chiamata allo strumento
• The confirmation could not be written to team-lead's inbox.: l'approvazione dell'arresto in sé ha avuto effetto e il compagno di squadra esce; manca solo la conferma al lead

Quando sei tu a mandare un messaggio a un compagno di squadra, digitando @name seguito dal messaggio nella sessione del lead, lo stesso errore appare come notifica, Couldn't write to @name's inbox — message not sent. Try again., e Claude Code mantiene il tuo testo nella casella del prompt in modo che tu possa inviarlo di nuovo.

Cosa fare:

• Chiedi al mittente di inviare di nuovo il messaggio; la contesa per il blocco della casella di posta è transitoria e si risolve con un nuovo tentativo
• Controlla lo spazio libero su disco, e verifica che ~/.claude/teams e i file al suo interno siano scrivibili dal tuo utente

Teammate's agent definition was not restored

Claude ha mandato un messaggio a un compagno di squadra arrestato di un team di agenti, e Claude Code l'ha riattivato senza riapplicare la definizione del subagent da cui era stato generato, perché il suo file di definizione proveniva da una cartella senza fiducia salvata. L'avviso segue il resoconto della ripresa nel risultato dello strumento dell'agente mittente:

Its agent definition was not restored: the folder its definition file came from is not trusted (source: projectSettings), so the teammate is running with the team-essential tools and no custom instructions. To restore it, the user needs to run Claude Code in that folder once and accept the trust dialog (the --debug log names the folder); do not change trust settings on the user's behalf.

Il controllo si applica a una definizione nella directory .claude/agents/ del progetto o di una directory --add-dir, e accettare la finestra di dialogo di fiducia per una cartella padre non lo soddisfa.

Cosa fare:

• Esegui claude nella cartella indicata dal log di debug e accetta la finestra di dialogo di fiducia. La definizione viene riapplicata la prossima volta che Claude Code riattiva il compagno di squadra; non è necessario riavviare la sessione del lead
• Oppure imposta la voce hasTrustDialogAccepted su true in ~/.claude.json, usando la chiave esatta projects["<path>"] che il log di debug stampa

Message too large for cross-session delivery

Il messaggio cross-session di Claude a un'altra delle tue sessioni su questa macchina era troppo lungo per essere inviato. Claude Code l'ha rifiutato, e la sessione ricevente non ha ricevuto nulla. Il rifiuto appare nel risultato dello strumento della sessione mittente, non come banner nel tuo terminale. Indica entrambe le dimensioni e come far rientrare il messaggio nel limite:

Failed to send to api-worker: Message too large for cross-session delivery: the serialized message is 1,203,844 characters and the limit is 1,048,576. Shorten the message text — put bulk content in a file the recipient can read rather than in the message — or split it into smaller messages.

Inviare di nuovo lo stesso testo fallisce allo stesso modo.

Cosa fare:

• Chiedi a Claude di riassumere il messaggio, o di mettere il contenuto più corposo in un file e inviare il percorso del file
• Chiedi a Claude di suddividere il contenuto in diversi messaggi più brevi

Prima della v2.1.235, Claude Code segnalava un messaggio troppo grande come inviato. La sessione ricevente lo scartava senza leggerlo.

Too many messages to this session just now

Claude ha inviato una raffica rapida di messaggi cross-session a una delle tue sessioni su questa macchina, e la raffica ha raggiunto quanto accetta la casella di posta di quella sessione. Claude Code ha rifiutato l'invio successivo, e la sessione ricevente non ha ricevuto nulla da esso. Il rifiuto appare nel risultato dello strumento della sessione mittente, non come banner nel tuo terminale:

Failed to send to api-worker: Too many messages to this session just now: 30 were sent recently and more would be dropped by its rate limit, so this one was not sent. Batch what remains into one message, or wait a little before sending more.

Cosa fare:

• Di solito niente: Claude raggruppa il contenuto rimanente in un unico messaggio, o aspetta prima di inviarne altri
• Se sei stato tu a richiedere la raffica, chiedi a Claude di combinare ciò che rimane in un singolo messaggio

Prima della v2.1.236, Claude Code segnalava questi invii come inviati. La sessione ricevente li scartava senza leggerli.

Cross-session message was dropped at the recipient session's inbox

Claude ha inviato un messaggio cross-session a un'altra delle tue sessioni su questa macchina, e la casella di posta di quella sessione l'ha scartato prima che Claude in quella sessione lo leggesse. La riga indica l'indirizzo del destinatario e, quando il destinatario ha fornito un motivo, aggiunge il motivo dopo un trattino:

Cross-session message was dropped at the recipient session's inbox (recipient: uds:/tmp/cc-socks/13605.sock) and not delivered — its queue of undelivered peer messages was full. Claude was told not to resend right away.

Una riga può riguardare diversi messaggi scartati. In tal caso inizia al plurale, ad esempio Cross-session messages (12) were dropped. Per scoprire a quale sessione appartiene un indirizzo, confrontalo con la riga Peer address che /status mostra in ogni sessione.

Dopo il trattino, la riga fornisce uno o più di questi motivi:

• its queue of undelivered peer messages was full: il destinatario conteneva già tanti messaggi non consegnati da altre sessioni quanti ne consente la sua coda
• you sent faster than that session accepts: i messaggi della sessione mittente sono arrivati più velocemente di quanto il destinatario accetti da un singolo mittente
• it repeated your previous message: il messaggio era identico a uno che la sessione mittente aveva inviato a questo destinatario poco prima
• a relay loop between sessions was cut: il messaggio proseguiva una catena di sessioni che si scambiavano messaggi, e la catena era passata per il destinatario troppe volte o era diventata troppo lunga

Cosa fare:

• Considera che il destinatario non abbia mai visto i messaggi scartati. Claude Code dice lo stesso a Claude, e gli dice di includere tutto ciò che conta ancora in un unico messaggio successivo invece di inviarlo di nuovo subito
• Se le tue sessioni si scambiano aggiornamenti frequenti, chiedi a Claude di inviare meno messaggi ma più corposi, come un unico resoconto quando una sessione termina il suo lavoro
• Per a relay loop between sessions was cut, digita tu stesso l'istruzione successiva in una delle sessioni. Un messaggio che Claude invia in risposta a un tuo prompt inizia una nuova catena

Prima della v2.1.238, la sessione mittente non riceveva alcun resoconto quando la casella di posta del destinatario scartava un messaggio.

Refusing to send a cross-session message

Prima che Claude Code scriva un messaggio cross-session a un'altra delle tue sessioni su questa macchina, verifica che il socket della casella di posta della sessione di destinazione sia l'endpoint a cui il messaggio era indirizzato. Quando un controllo fallisce, Claude Code rifiuta l'invio nella sessione mittente, e la sessione di destinazione non riceve nulla. Per un messaggio inviato da Claude, il rifiuto appare nel risultato dello strumento della sessione mittente:

Failed to send to api-worker: Refusing to send: reply target is a symlink

Il testo dopo Refusing to send: indica il controllo che è fallito:

• reply target is a symlink: nel percorso del socket della sessione di destinazione si trova un collegamento simbolico. Claude Code non consegna attraverso di esso, perché un collegamento in quel punto potrebbe reindirizzare il messaggio a un endpoint che la sessione di destinazione non ha creato.
• cannot vet reply target: Claude Code non è riuscito in alcun modo a ispezionare il percorso di destinazione, ad esempio perché la lettura è fallita con un errore di permesso.

Cosa fare:

• Di solito niente: i controlli impediscono a un messaggio di raggiungere un endpoint diverso dalla sessione a cui era indirizzato, e non è stato inviato nulla
• Se reply target is a symlink si ripete per una sessione, verifica cosa ha creato un collegamento nel percorso del socket di quella sessione, mostrato nel suo /status sotto Peer address

Refusing to read, write, or search a path

Claude Code verifica le regole di permesso di un percorso file, poi conferma di nuovo quella risoluzione quando lo strumento apre il file o avvia la ricerca. Quando non riesce a confermare che il percorso conduca ancora alla posizione approvata dal controllo, Claude Code rifiuta l'operazione invece di seguirlo. Il rifiuto appare nel risultato dello strumento:

Refusing to read /path/to/file: its symlink resolution changed after permission was checked (a link on the way now leads somewhere the check did not see). If a link in the working directory is being rewritten concurrently, stop that and retry.

Ogni rifiuto indica il proprio motivo:

• its symlink resolution changed after permission was checked: un collegamento simbolico lungo il percorso, o in una radice di ricerca di Grep o Glob, è stato sostituito tra il controllo dei permessi e l'operazione. In un rifiuto di lettura, la frase tra parentesi indica quale confronto è fallito.
• its parent-directory symlink resolution changed after permission was checked: una directory attraversata dal percorso di scrittura non si risolve più nella posizione approvata
• where it leads on disk could not be determined (a link on the way could not be examined, or the links do not resolve): Claude Code non è riuscito a seguire il percorso fino a una posizione finale su disco, ad esempio perché i collegamenti simbolici lungo di esso formano un ciclo
• it is a symbolic link. Write to the link's target path instead: un collegamento simbolico si trova nella posizione di scrittura richiesta stessa, ad esempio un CLAUDE.md che è un collegamento simbolico a AGENTS.md; il messaggio indirizza Claude alla destinazione del collegamento
• Refusing to write through symlink: <path>. Resolve the symlink and pass the real target path explicitly.: la stessa condizione rilevata quando un altro componente di scrittura apre il file, come una scrittura su un .mcp.json che è un collegamento simbolico
• Refusing to write into symlinked directory: <path>: la directory che contiene il file è essa stessa un collegamento simbolico, ad esempio la directory .claude/ di un progetto collegata a un'altra posizione
• a path one of its Read deny rules is written through changed while the search was being prepared. Retry.: una regola di negazione Read per la ricerca nomina un percorso che passa attraverso un collegamento simbolico, e quel collegamento è cambiato mentre Claude Code stava preparando la ricerca
• it could not be opened (EACCES) — it is unreadable, or is being replaced concurrently.: la radice di ricerca esiste ma non è stato possibile aprirla; il codice tra parentesi è l'errore del sistema operativo
• its permission check expired before it ran (too many concurrent file operations). Retry.: Claude Code ha rimosso il record di approvazione, a causa di molte operazioni simultanee sui file, prima che lo strumento lo usasse; riprovare esegue un nuovo controllo dei permessi
• ripgrep was found only by name on PATH, and a search outside the working directory cannot apply your Read deny rules in that configuration: Claude Code non è riuscito a risolvere il binario rg in un percorso assoluto, quindi rifiuta le ricerche al di fuori della directory di lavoro invece di eseguirne una non coperta dalle tue regole di negazione

Cosa fare:

• Di solito niente: il rifiuto raggiunge Claude come risultato dello strumento, e l'operazione rifiutata non viene eseguita
• Se un rifiuto dovuto a un collegamento simbolico si ripete su un percorso, individua cosa continua a riscrivere un collegamento in quel punto, come uno strumento di build o un file watcher, oppure chiedi a Claude di usare il percorso risolto del file invece di quello collegato
• Se questo rifiuto appare per ogni file mentre Claude Code è in esecuzione su Windows all'interno di un AppContainer o di una sandbox con token limitato, aggiorna alla v2.1.265 o successiva
• Se su macOS appare un rifiuto di lettura per un file che nulla sta riscrivendo, come uno screenshot trascinato nel prompt, aggiorna alla v2.1.273 o successiva
• Per il rifiuto relativo a ripgrep, installa ripgrep con il tuo gestore di pacchetti in modo che rg si risolva in un percorso assoluto su PATH, oppure mantieni le ricerche all'interno della directory di lavoro

Prima della v2.1.251, Claude Code ricontrollava la risoluzione di un percorso solo per le scritture di file, quindi un collegamento sostituito dopo il controllo dei permessi poteva reindirizzare una lettura o una ricerca a una posizione diversa senza alcun messaggio. Tra questi, solo i rifiuti di scrittura relativi alla directory padre, alla scrittura attraverso un collegamento simbolico e alla directory collegata simbolicamente appaiono nelle versioni precedenti.

Prima della v2.1.280, il rifiuto where it leads on disk could not be determined non appariva.

Task output swap refused

Claude Code salva l'output di ogni comando Bash in un file all'interno della sua directory temporanea. Ogni volta che apre uno di questi file, verifica che il percorso conduca ancora al file che ha creato, senza alcun collegamento simbolico, collegamento fisico aggiuntivo o directory spostata che lo reindirizzi. Questo messaggio significa che quel controllo è fallito, quindi Claude Code ha rifiutato l'operazione invece di scrivere o leggere l'output attraverso quel percorso. Il messaggio appare nel risultato dello strumento Bash:

task output swap refused (tasks dir moved or linked): /private/tmp/claude-501/-Users-you-my-project/1f0e62dc-4b0a-4f5e-9c2d-8a7b6c5d4e3f/tasks/b7k2f9m3q.output. To recover: restart Claude Code with CLAUDE_CODE_TMPDIR set to a fresh directory; or, if /private/tmp/claude-501/-Users-you-my-project is a stray directory or a symbolic link that should not be there, remove that entry itself (not what it points to) and restart.

Il testo tra parentesi indica il controllo che è fallito. Motivi come output symlink was re-pointed, output file identity changed e not a regular file segnalano tutti la stessa condizione: qualcosa nel percorso dell'output o lungo di esso non è più il file che Claude Code ha creato. Solo alcuni motivi includono una frase To recover:.

Se il controllo fallisce mentre un comando è ancora in esecuzione, Claude Code interrompe il comando, e il suo risultato riporta:

Command killed: its output file was replaced or could no longer be verified

Cosa fare:

• Aggiorna alla v2.1.260 o successiva. Le versioni precedenti a volte mostravano questo messaggio anche quando non era presente alcun collegamento o directory spostata
• Riavvia Claude Code con CLAUDE_CODE_TMPDIR impostato su una directory nuova
• Oppure controlla la directory del tuo progetto all'interno della directory temporanea di Claude Code, /private/tmp/claude-501/-Users-you-my-project nel messaggio di esempio. Se quel percorso è un collegamento simbolico, o una directory che non dovrebbe trovarsi lì, rimuovi il collegamento o la directory stessa invece della destinazione del collegamento, e riavvia Claude Code
• Se il rifiuto si ripete, un processo sta sostituendo, collegando o rimuovendo voci nella directory temporanea di Claude Code mentre la sessione è in esecuzione. Imposta CLAUDE_CODE_TMPDIR su una directory non gestita da nient'altro e riavvia

Disk quota or temp filesystem is full

Claude Code salva l'output di ogni comando Bash e PowerShell in un file all'interno della sua directory temporanea. Quando un comando termina con un codice diverso da zero e senza alcun output, Claude Code verifica se il file system che contiene quel file ha esaurito lo spazio o gli inode, o se la tua quota disco su di esso è esaurita. In tal caso, nel risultato del comando appare una diagnostica al posto dell'output vuoto:

Your disk quota is full on the filesystem with Claude Code's temp directory /private/tmp/claude-501/-Users-you-my-project/1f0e62dc-4b0a-4f5e-9c2d-8a7b6c5d4e3f/tasks (EDQUOT), so any output this command printed was lost, and it may have failed because it could not write. Delete files you no longer need there, or restart Claude Code with CLAUDE_CODE_TMPDIR set to a directory on another filesystem.

Il messaggio indica cosa è esaurito:

• Your disk quota is full ... (EDQUOT): la tua quota su quel file system è esaurita. Una quota può essere piena anche quando il file system mostra ancora spazio libero
• The filesystem with Claude Code's temp directory ..., or your disk quota on it, is full (ENOSPC): il file system, o la tua quota su di esso, non ha più spazio
• Command output was lost: the temp filesystem at ... is full o ... is out of inodes: il file system non ha quasi più spazio libero, o sta esaurendo gli inode

Cosa fare:

• Elimina i file che non ti servono più sul file system che contiene la directory temporanea di Claude Code. Per EDQUOT, elimina i file che contano ai fini della tua quota. Per out of inodes, elimina molti file invece di pochi file grandi, poiché ogni file occupa un inode indipendentemente dalla sua dimensione
• Oppure riavvia Claude Code con CLAUDE_CODE_TMPDIR impostato su una directory in un file system con spazio disponibile
• Poi chiedi a Claude di eseguire di nuovo il comando. L'output che aveva stampato è andato perso, non troncato

The source file is not valid UTF-8 text

Claude ha tentato di pubblicare un artefatto da un file i cui byte non si decodificano come testo, o il cui testo contiene già il carattere di sostituzione U+FFFD, quindi Claude Code ha rifiutato la pubblicazione prima di caricare qualsiasi cosa. Il messaggio appare nel risultato dello strumento Artifact e indica la prima posizione da correggere:

file_path: the source file is not valid UTF-8 text (first invalid byte at line 12, column 40). It may be saved in another encoding or contain binary data. Rewrite it as UTF-8, then publish again. Nothing was published.

file_path: the source file has the replacement character U+FFFD at line 12, column 40, usually left where an earlier edit or paste lost a character. Replace it with the intended text (in HTML, write an intended U+FFFD as �), then publish again. Nothing was published.

Claude Code decodifica il file come UTF-8, o come UTF-16 quando inizia con un byte order mark UTF-16 little-endian. Quando un file UTF-16 di questo tipo non si decodifica, il primo messaggio nomina UTF-16 e ti dice comunque di riscrivere il file come UTF-8. Quando altre posizioni seguono quella indicata, il messaggio aggiunge un conteggio come (+2 more) dopo la posizione.

Cosa fare:

• Di solito niente: Claude riscrive il file e lo pubblica di nuovo
• Se il file è uno che hai scritto o esportato tu, salvalo di nuovo come UTF-8, e sostituisci ogni U+FFFD con il carattere perso in una precedente modifica, operazione di incolla o conversione
• Per mostrare un U+FFFD intenzionale nella pagina, scrivilo come � nell'HTML invece del carattere letterale

Prima della v2.1.267, Claude Code caricava un file di questo tipo senza controllarlo, e il server rifiutava invece la pubblicazione.

Not published: that file is on a network share

Claude ha tentato di pubblicare un artefatto da un file in un percorso che nomina un host di rete:

• Su Windows, un percorso \\server\share che non si trova in un'unità di rete mappata che hai passato all'avvio con --add-dir
• Su macOS o Linux, un percorso di automount come /net/<host>/page.html

La risoluzione di un percorso di questo tipo contatta l'host che nomina, e su Windows quel contatto può inviare all'host le tue credenziali. Claude Code rifiuta di pubblicare il file e non lo legge. Il rifiuto appare nel risultato dello strumento Artifact:

Not published: that file is on a network share. Publish a file from this session's folders instead.

Cosa fare:

• Niente, se non ti serve proprio quel file: il messaggio dice a Claude di pubblicare invece un file dalle cartelle della sessione
• Per pubblicare proprio quel file, copialo in una cartella su un disco locale e chiedi di nuovo
• Su Windows, per permettere a Claude di pubblicare direttamente dalla condivisione, mappala a una lettera di unità e passa l'unità quando avvii Claude Code. In PowerShell, ad esempio, esegui net use Z: \\server\share e poi claude --add-dir Z:\. Claude potrà quindi pubblicare file da quell'unità. Aggiungere l'unità a sessione in corso con /add-dir non è sufficiente.
• Su macOS o Linux, monta la condivisione in una directory come una sotto /mnt o /Volumes, e pubblica da quel percorso invece che dal percorso di automount

Reading a local file from outside the connected folders in a Cowork session

In una sessione Cowork in esecuzione sulla tua macchina nell'app Claude Desktop, Claude ha indicato un file locale per un artefatto. Claude Code non è riuscito a confermare che il file sia un file semplice all'interno delle cartelle connesse della sessione: il percorso si trova al di fuori di quelle cartelle, passa attraverso un collegamento simbolico, o è scritto in un modo che può indicare un file diverso da quello che sembra. Leggere un file di questo tipo richiede la tua approvazione, e in una sessione che non può mostrarti la scheda di approvazione, come una impostata per saltare tutte le approvazioni, Claude Code rifiuta la lettura.

Il rifiuto appare nel risultato dello strumento Artifact; quando non è stato possibile esaminare il file in alcun modo, indica invece quell'errore:

Reading a local file from outside this session's connected folders, or through a link, needs the approval card, and no one can answer it in this Cowork session. Use a plain file inside the connected folders; do not retry this file in this session.

cannot read file_path (ENOENT) — the file could not be examined, and no one can answer the approval card in this Cowork session. Check that the file exists as a plain file inside the connected folders, then retry with that path.

Cosa fare:

• Di solito niente: il messaggio dice a Claude di usare invece un file semplice all'interno delle cartelle connesse
• Per inserire proprio quel file nell'artefatto, copialo in una delle cartelle connesse della sessione come file normale, non come collegamento simbolico, e chiedi di nuovo

WebFetch cannot fetch localhost

Claude ha chiamato WebFetch con un URL il cui hostname non contiene un punto, come http://localhost:3000 o un semplice nome intranet come http://wiki/. WebFetch rifiuta questi URL prima di effettuare qualsiasi richiesta:

WebFetch cannot fetch localhost or other hostnames without a dot. To reach a local server, use Bash with curl instead.

Cosa fare:

• Di solito niente: il messaggio indirizza Claude verso curl tramite lo strumento Bash, che può raggiungere server locali e intranet

Prima della v2.1.268, WebFetch segnalava questi URL con un errore generico Invalid URL.

WebFetch domain safety check failed

Prima di recuperare un URL, WebFetch invia l'hostname dell'URL a api.anthropic.com per verificarlo rispetto alla lista di blocco per la sicurezza dei domini di Anthropic. Se il controllo non può essere completato, WebFetch non può confermare che il dominio sia sicuro, quindi non recupera la pagina e il risultato dello strumento riporta invece uno di questi messaggi:

The safety check for domain example.com is rate-limited (too many domain checks from this network; the limit is shared and can stay exhausted for minutes). Do not retry WebFetch in a loop or sleep to wait it out; continue without this page and report that its safety check was rate-limited. A single later attempt is fine; if that is rate-limited too, stop.

Unable to verify if domain example.com is safe to fetch. This may be due to network restrictions or enterprise security policies blocking claude.ai.

• rate-limited: l'endpoint di controllo ha risposto con HTTP 429. Il messaggio dice a Claude di continuare senza la pagina e di riprovare al massimo una volta più tardi. Claude Code non memorizza nella cache un controllo fallito, quindi un successivo recupero di quel dominio esegue di nuovo il controllo. Se le sessioni sulla tua rete incontrano spesso questo errore, puoi saltare il controllo con skipWebFetchPreflight: true nelle impostazioni.
• Unable to verify: la richiesta di controllo è fallita, è andata in timeout o ha ricevuto un altro stato di errore. Se la tua rete blocca api.anthropic.com, aggiungi quel dominio all'allowlist, oppure salta il controllo con skipWebFetchPreflight: true nelle impostazioni.

Prima della v2.1.286, il messaggio di rate limit riportava The safety check for domain example.com is temporarily rate-limited (too many domain checks from this network). Retry after about a minute; retrying sooner will fail the same way.. Prima della v2.1.285, un controllo soggetto a rate limit veniva invece segnalato con il messaggio Unable to verify.

Errori di sessione in background

Le sessioni in background vengono eseguite senza un terminale interattivo proprio, quindi i comandi che ne richiedono uno si comportano diversamente lì. Questi messaggi appaiono nella trascrizione di una sessione in background, nel terminale che si collega a una, nella sessione o shell da cui si invia, o, per le voci worktree-guard di seguito, in qualsiasi sessione isolata in un worktree o che esegue un subagent isolato da worktree; dove un messaggio è specifico di una superficie, la sua voce lo dice.

Comandi rifiutati in una sessione in background

I comandi che aprono una finestra di dialogo interattiva non possono farlo mentre nessun terminale è collegato a una sessione in background. /install-github-app, l'elenco delle impostazioni /mcp e le azioni di autenticazione nel menu del server MCP rispondono con un messaggio. Per /install-github-app e l'elenco delle impostazioni /mcp, la sessione appare anche sotto Needs input nella vista agente in modo che tu possa trovarla, collegarti ed eseguire di nuovo il comando. Mentre un terminale è collegato, questi comandi funzionano normalmente.

Prima della v2.1.216, la sessione non appariva sotto Needs input dopo il rifiuto di /install-github-app o dell'elenco delle impostazioni /mcp. Nella v2.1.213 attraverso v2.1.215, i comandi funzionavano ancora mentre un terminale era collegato, e il messaggio di rifiuto ti diceva di collegarti ed eseguire di nuovo il comando. Dalla v2.1.208 attraverso v2.1.212, Claude Code li rifiutava anche mentre un terminale era collegato, con un messaggio come Can't open MCP settings in a background session; su quelle versioni, esegui il comando da una sessione claude regolare invece, o esegui l'upgrade. Prima della v2.1.208, aprivano la loro finestra di dialogo all'interno della sessione in background. Solo nella v2.1.208, Claude Code ha anche rifiutato il selettore /model in una sessione in background, e /upgrade ha stampato l'URL di upgrade invece di aprire un browser.

La formulazione nomina il comando. L'elenco delle impostazioni /mcp riporta:

Can't open MCP settings while no terminal is attached to this background session. This session now shows "needs input" in agent view — open it and run /mcp to manage servers, or use `/mcp enable|disable|reconnect <server>` to steer without the panel.

Cosa fare:

• Collegati alla sessione dalla vista agente e esegui di nuovo il comando
• Oppure usa il modulo che il messaggio nomina, come /mcp reconnect <server>, /mcp enable, o /mcp disable, che funzionano senza collegarsi

Scrittura o comando bloccato perché il percorso non può essere risolto in modo sicuro

Claude ha indirizzato un file o una directory di lavoro attraverso un'ortografia che la guardia di isolamento worktree non può risolvere in un'unica posizione verificabile. La guardia controlla le scritture e le directory di lavoro dei comandi in qualsiasi sessione isolata in un worktree, interattiva o in background, e in subagent isolati da worktree. Risolve i collegamenti simbolici prima di controllare che l'operazione non raggiunga il checkout condiviso, e quando la risoluzione fallisce, blocca l'operazione piuttosto che lasciarla atterrare lì. Il messaggio nomina le forme di percorso che rifiuta e come riprovare:

This write was blocked because the path is spelled in a form that cannot be safely resolved (for example through a symlink storing a raw dot segment, a network-share or device-namespace shape, or an unreadable ancestor directory). If the file is inside the worktree /path/to/worktree, address it by its direct symlink-free path instead.

Un comando bloccato riporta la stessa causa per la sua directory di lavoro e termina con re-run the command from its direct symlink-free path. Prima della v2.1.217, la guardia confrontava le ortografie dei percorsi senza risolvere i collegamenti simbolici, quindi queste ortografie non erano bloccate e una scrittura instradata attraverso un collegamento simbolico poteva atterrare nel checkout condiviso.

Cosa fare:

• Di solito nulla: il messaggio completo va a Claude come errore dello strumento, e Claude riprova con il percorso diretto che nomina. Per una modifica di file bloccata, la vista della conversazione mostra solo una breve riga Error editing file; il messaggio completo appare nella vista della trascrizione, che apri con Ctrl+O. Un comando bloccato lo stampa nel suo output di comando.
• Se il blocco si ripete sullo stesso file, il percorso probabilmente passa attraverso un collegamento simbolico sottoposto a commit il cui target contiene .., come docs/current -> ../README.md; chiedi a Claude di modificare il file target dal suo percorso reale invece che attraverso il link

Scrittura o comando bloccato perché il percorso nomina una posizione di rete

Claude ha indirizzato un file o una directory di lavoro attraverso un percorso che nomina un'unità che non è sulla tua macchina, una condivisione UNC come \\server\share\file o un percorso di automount /net, mentre il checkout della sessione è su un disco locale. La stessa guardia di isolamento worktree non può verificare che tale percorso rimanga fuori dal checkout condiviso, quindi blocca l'operazione. Isolare la sessione in un worktree non solleva il blocco. Il messaggio nomina la forma di percorso da usare invece:

This write was blocked because the path is network-shaped (a UNC share or /net automount spelling) while this session's checkout is local. Isolating cannot unblock it. If the file is genuinely inside the worktree /path/to/worktree, address it by its local, plainly-spelled path instead.

Un comando bloccato riporta la stessa causa per la sua directory di lavoro e termina con re-run the command from its local, plainly-spelled path. Prima della v2.1.217, la guardia confrontava solo il testo del percorso, quindi indirizzare un file all'interno del checkout attraverso un percorso UNC o /net non era bloccato.

Cosa fare:

• Di solito nulla: Claude riprova con l'ortografia locale che il messaggio chiede

Comando bloccato dai controlli di isolamento worktree

Claude ha eseguito un comando Bash o Monitor in una sessione isolata in un worktree, e Claude Code l'ha rifiutato per uno di due motivi:

• Il comando punta git al checkout principale.
• Claude Code non può verificare dal testo del comando che qualsiasi git che il comando esegue rimanga all'interno del worktree. Un comando che non nomina mai git può comunque essere rifiutato per questo motivo, perché espandere un'indirezione di variabile come ${!name} o eseguire una sostituzione di funzione Bash come ${ command; } produce un valore in fase di esecuzione che può essere esso stesso un comando.

Il mezzo del messaggio nomina cosa non poteva essere verificato:

This session is isolated in the worktree /path/to/worktree, but this command evaluates ${!x@P} arithmetically inside a construct too complex to verify, which can run a command hidden in a variable's value. Refusing to run it — a worktree-isolated session's git operations must target its own worktree. Split it into plain, separate commands and run them from /path/to/worktree.

Cosa fare:

• Di solito nulla: Claude legge il messaggio e riscrive il comando nel modo che la sua frase finale chiede
• Se un comando che hai chiesto continua ad essere rifiutato, scrivi il valore contrassegnato letteralmente: sostituisci l'indirezione o la sostituzione con il suo valore, ed esegui git come suo proprio comando semplice dall'interno del worktree
• Per agire sul checkout principale di proposito, esegui il comando tu stesso in un terminale al di fuori della sessione

Questa sessione non ha una trascrizione salvata

Hai collegato una sessione in background interrotta che è stata messa in background da un'altra conversazione con ← o /background e interrotta prima che la sua prima risposta finisse. Fino a quando quella prima risposta non finisce, la conversazione vive ancora solo nella sessione da cui è stata messa in background, quindi claude attach rifiuta di avviare la sessione interrotta piuttosto che iniziare una conversazione vuota con lo stesso ID di sessione. Il messaggio termina con il comando claude respawn per questa sessione:

This session has no saved transcript — it was stopped before its first response finished. If it was backgrounded from another conversation, that one is still intact; `claude respawn <id>` starts this one fresh.

Aprire la stessa riga della sessione nella vista agente mostra Press enter again to restart this session fresh sotto l'elenco invece, e un secondo Enter sulla riga riavvia la sessione con una conversazione vuota. Prima della v2.1.212, aprire la riga mostrava il messaggio di rifiuto senza modo di riavviare dalla vista agente. Prima della v2.1.211, aprire la sessione interrotta avviava silenziosamente quella conversazione vuota e poteva rieseguire il prompt originale della sessione.

Cosa fare:

• La conversazione che hai messo in background è intatta: riprendi con claude --resume o continua a lavorarci
• Per avviare la sessione interrotta da zero comunque, esegui claude respawn <id> con l'ID dal messaggio, o premi Enter due volte sulla sua riga nella vista agente
• Se la sessione ha finito una risposta e vedi ancora questo rifiuto su una versione prima della v2.1.214, una cartella illeggibile in ~/.claude/projects potrebbe far sì che la scansione della trascrizione perda la conversazione salvata; aggiorna alla v2.1.214 o successiva, che tollera le cartelle illeggibili durante la scansione

Questa sessione è in esecuzione in un altro terminale

Hai aperto la riga di una sessione interrotta nella vista agente, e la sua conversazione salvata è già aperta in un altro processo Claude Code attivo su questa macchina, quindi Claude Code rifiuta di avviare un secondo processo che scriverebbe sulla stessa trascrizione. Quale messaggio vedi dipende da cosa tiene la conversazione:

Can't open — this session is running in another terminal
This conversation is already open in another running Claude session — use that one, or close it and try again

• running in another terminal: un terminale tiene la conversazione, ad esempio uno in cui l'hai ripresa con claude --resume o /resume. La riga mostra anche Open in a terminal.
• already open in another running Claude session: un altro processo Claude Code non interattivo la tiene, ad esempio un processo sessione in background per la stessa conversazione che non è ancora uscito.

Claude Code salva una risposta che hai digitato quando apri la riga e la invia come il prossimo prompt della sessione quando la sessione si avvia di nuovo.

Cosa fare:

• Continua la conversazione nel processo che l'ha aperta, o esci da quel processo e apri di nuovo la riga

Prima della v2.1.248, esisteva solo il rifiuto already open in another running Claude session: una conversazione ripresa in un terminale non contava come aperta, e aprire la riga avviava un secondo processo Claude Code che scriveva sulla stessa conversazione.

La conversazione salvata di questa sessione non è più su disco

Hai aperto una sessione in background che è terminata mentre il servizio in background era spento, e la pulizia della trascrizione ha da allora rimosso la sua conversazione salvata, ad esempio dopo che la macchina è stata spenta per settimane. Aprire una tale riga normalmente riprende la sua conversazione salvata. Non avendo nulla da riprendere, Claude Code rifiuta piuttosto che rieseguire il prompt originale della sessione senza chiedere:

This session's saved conversation is no longer on disk (it ended while the background service was off, and old transcripts are cleaned up), so there is nothing to resume. `claude rm 7c5dcf5d` deletes the row; `claude respawn 7c5dcf5d` runs its original prompt again instead.

claude attach <id> stampa questo testo. Nella vista agente, il piè di pagina è più breve e termina con ctrl+x deletes the row.

Cosa fare:

• Esegui claude rm <id> per eliminare la riga. Quando uno dei casi mantenuti si applica, claude rm mantiene la riga e il worktree invece e nomina il motivo
• Per eseguire di nuovo il prompt originale della sessione come una conversazione fresca, esegui claude respawn <id>

Prima della v2.1.248, aprire una tale riga rieseguiva il prompt originale della sessione invece di rifiutare, tirando un compito di settimane fa in primo piano.

Worktree ha commit che non sono spinti da nessuna parte

Hai provato a eliminare una sessione in background il cui worktree contiene commit che Claude Code non può confermare siano salvati altrove. Claude Code mantiene il worktree e la riga della sessione piuttosto che distruggere i commit senza vederli. claude rm nomina il branch e i commit non spinti, e dice come procedere:

kept 7c5dcf5d — its worktree is still at “/home/you/project/.claude/worktrees/fix-login”
  2 unpushed commits on “claude/fix-login”: a1b2c3d “Fix login flow” and 1 more. They exist on no remote, so deleting the worktree would lose them.
  push them and run 'claude rm 7c5dcf5d' again, or discard the worktree and its commits: claude rm 7c5dcf5d --discard-unpushed a1b2c3d000000000000000000000000000000000@0123456789abcdef0123456789abcdef

Quando Claude Code non può riassumere i commit, la riga di dettaglio legge The worktree has unpushed commits invece. Nella vista agente, la riga della sessione mostra not deleted con lo stesso motivo.

I commit su un remote non bloccano l'eliminazione. Nemmeno i commit sulla copia locale del branch predefinito del tuo remote origin, purché quel branch sia estratto nel tuo checkout principale, la directory del repository stesso piuttosto che un worktree.

Cosa fare:

• Per mantenere i commit, esegui il push del branch del worktree, o esegui il merge nel branch predefinito estratto nel tuo checkout principale, quindi elimina di nuovo la sessione
• Per scartare i commit, esegui il comando claude rm <id> --discard-unpushed che il messaggio ha stampato, o premi Ctrl+X due volte sulla riga della sessione nella vista agente di nuovo. Questo rimuove la sessione e il worktree insieme al suo branch, ai commit non spinti e a qualsiasi modifica non sottoposta a commit. Se il worktree ha guadagnato un commit dal rifiuto, Claude Code lo mantiene di nuovo e mostra lo stato aggiornato
• Quando il messaggio dice che il worktree è anche registrato da un'altra sessione terminata, eliminare di nuovo non lo scarta: esegui il push dei commit, quindi elimina di nuovo la sessione

Prima della v2.1.268, claude rm metteva il riassunto del commit sulla riga kept stessa. Quando claude rm non poteva riassumere i commit, la riga kept leggeva worktree has commits that are not pushed anywhere al posto del riassunto.

Prima della v2.1.260, il messaggio non nominava il branch o i commit, e eliminare di nuovo era rifiutato allo stesso modo: eliminare la sessione senza eseguire il push significava rimuovere il worktree tu stesso con git worktree remove --force <path>, quindi eseguire di nuovo claude rm <id>.

Prima della v2.1.248, il branch predefinito estratto nel tuo checkout principale non contava: un branch di cui avevi già eseguito il merge lì attivava ancora questo rifiuto fino a quando i suoi commit non raggiungevano un remote.

Il processo host del terminale è morto

Ogni terminale della sessione in background viene eseguito in un processo host sotto il servizio in background, e quel processo è morto mentre il servizio manteneva ancora la sua connessione, quindi la sessione non poteva essere raggiunta.

Su Linux e WSL, il servizio in background controlla ogni processo host ogni pochi secondi, contrassegna la sessione come fallita quando il processo è uscito ma la sua connessione al servizio non si è mai chiusa, e mostra il motivo sulla sua riga nella vista agente:

terminal host process died — press Enter to restart

Dalla shell, claude attach <id> riavvia una sessione già contrassegnata come fallita per un host morto, e altrimenti stampa il motivo e esce:

Couldn't attach to <id> — This session's terminal host process died (the conversation is saved) — run `claude attach <id>` again to restart it on a fresh host.

La conversazione è salvata comunque.

Una riga che esegue un comando shell invece mostra terminal host process died — its output is gone; the command was not run again, e claude attach stampa This command's terminal host process died — its output is gone and the command was not run again. Claude Code non riesegue mai il comando per te.

Cosa fare:

• Nella vista agente, premi Enter sulla riga fallita; la sessione si riavvia su un nuovo processo host e la conversazione riprende
• Dalla shell, esegui di nuovo claude attach <id>. Claude Code stampa Session <id>'s terminal host died — restarting it on a fresh one… e riapre la sessione
• Non puoi riavviare una riga di comando shell in questo modo; invia di nuovo il comando per rieseguirlo

Prima della v2.1.247, un processo host morto poteva passare ogni controllo di vitalità che il servizio in background eseguiva, quindi aprire la sessione mostrava opening… · esc to cancel indefinitamente e claude attach <id> aspettava senza segnalare un errore.

La sessione non sta rispondendo

Hai aperto una sessione in background e il servizio in background ha accettato l'apertura, ma nessun output è arrivato per circa dieci secondi, quindi Claude Code conclude che il processo che trasmette il terminale della sessione non può fornire output, e termina il tentativo invece di aspettare.

Nella vista agente, Claude Code offre un riavvio nel piè di pagina:

Press enter again to restart this session — it isn't responding (its conversation is saved and resumes).

Dalla shell, claude attach <id> stampa il motivo e esce:

Couldn't attach to <id> — Session isn't responding — `claude stop <id>`, then `claude attach <id>` restarts it (the conversation is saved).

Claude Code non riavvia mai una riga che esegue un comando shell per te, perché un riavvio rieseguirebbe il comando.

Cosa fare:

• Nella vista agente, premi Enter sulla stessa riga di nuovo. Claude Code interrompe il processo che non risponde e riavvia la sessione, e la conversazione riprende. Nulla viene interrotto senza quella seconda pressione
• Dalla shell, esegui claude stop <id>, quindi claude attach <id>
• Per una riga di comando shell, premi Ctrl+X nella vista agente o esegui claude stop <id> per interromperla; invia di nuovo il comando per rieseguirlo

La sessione è stata interrotta mentre il respawn era in volo

Hai aperto una sessione in background il cui processo non era in esecuzione, e mentre Claude Code la stava riavviando, un altro processo Claude Code l'ha interrotta, ad esempio claude stop in un altro terminale. Claude Code mantiene la sessione interrotta:

Session <id> was stopped while the respawn was in flight

Aprire una sessione che hai appena inviato, mentre il suo processo è ancora in avvio, aspetta il processo invece. Prima della v2.1.246, aprirla in quel momento poteva interromperla e mostrare questo messaggio.

Cosa fare:

• Se non hai interrotto la sessione, apri di nuovo la sua riga nella vista agente o esegui claude respawn <id> per riavviarla
• Se l'hai interrotta tu stesso, non rimane nulla da fare: la sessione rimane interrotta

Agente della sessione non più disponibile

Hai ripreso una sessione che stava eseguendo un agente personalizzato, avviato con --agent o l'impostazione agent, e Claude Code non ha trovato un agente con quel nome. Cerca prima nella directory originale della sessione, quando hai fiducia in quel workspace, quindi nella directory da cui riprendi. La sessione riprende comunque, ma con gli strumenti predefiniti, quindi le restrizioni dello strumento dell'agente non si applicano più:

This session was running agent 'code-reviewer', which is no longer available (no agent by that name in /home/you/project). Continuing with the default tools and system prompt — the agent's tool restrictions no longer apply. To restore it, re-create the agent, or resume with an explicit --agent <name>.

L'avviso nomina solo le directory che Claude Code ha cercato, e appare nella conversazione ripresa sia che tu svegli una sessione in background, esegua /resume o claude --resume, o riprenda in modalità non interattiva, dove va anche a stderr. Le sessioni che usano --input-format stream-json non lo mostrano, perché l'Agent SDK fornisce agenti dopo l'avvio.

Claude Code non salva il fallback nella sessione, quindi l'avviso si ripete ad ogni ripresa fino a quando non agisci. L'agente claude integrato non attiva l'avviso, poiché ripiegare sul set di strumenti predefinito non cambia nulla per esso. Prima della v2.1.216, Claude Code continuava silenziosamente come l'agente predefinito, e la ricerca copriva solo la directory da cui riprendevi, quindi un agente con ambito di progetto era perso ad ogni ripresa da un'altra directory.

Cosa fare:

• Ricrea il file dell'agente in .claude/agents/<name>.md nel progetto della sessione, o in ~/.claude/agents/<name>.md per un agente personale, quindi riprendi di nuovo
• Oppure riprendi con --agent <name> nominando un agente che esiste, per eseguire la sessione come quell'agente invece
• Se l'agente ha ambito di progetto e non hai fiducia nella directory originale della sessione, esegui Claude Code lì una volta, accetta la finestra di dialogo di fiducia, quindi riprendi di nuovo

Errori del launcher CLAUDE\_CODE\_PROCESS\_WRAPPER

CLAUDE_CODE_PROCESS_WRAPPER è impostato, e il suo valore non può essere usato, quindi Claude Code rifiuta di avviare il processo interessato piuttosto che eseguirlo senza il launcher. I problemi di configurazione sono segnalati con un messaggio che inizia con il nome della variabile e dichiara il motivo, ad esempio:

CLAUDE_CODE_PROCESS_WRAPPER: launcher `/opt/corp/launcher` is not an executable regular file

Un launcher che si avvia ma esce senza sostituirsi con Claude Code fallisce la sessione che stava avviando, e la riga della sessione nella vista agente riporta che il launcher must exec, not daemonize, seguito da qualsiasi cosa il launcher abbia stampato. Una sessione che non può avviarsi o raggiungere il servizio in background a causa del launcher riporta il problema del launcher come motivo all'interno di Couldn't reach the background service (...).

Cosa fare:

• Imposta la variabile al percorso assoluto di un eseguibile che termina chiamando exec "$@". Vedi il contratto del launcher per il contratto completo
• Controlla /status, che mostra il comando di avvio risolto nella sua voce Self-exec e avverte quando il servizio in background in esecuzione non corrisponde, o esegui claude daemon status da una shell
• Dopo aver corretto il valore nel blocco env delle impostazioni, riavvia il servizio in background con claude daemon stop --any in modo che il prossimo invio avvii uno avvolto

EUNKNOWN quando si avvia una sessione in background

Windows ha rifiutato di avviare un programma con un codice di errore che non ha un nome standard, quindi l'errore emerge come EUNKNOWN. Il trigger solito è una politica di restrizione del software, come Group Policy o AppLocker, che blocca il programma in fase di avvio. L'errore appare quando avvii una sessione in background con /background o claude --bg:

Couldn't reach the background service (spawn background service: EUNKNOWN: unknown error, uv_spawn) — run 'claude daemon status'

Su alcuni account il messaggio dice daemon al posto di background service.

Su un'installazione npm, un EUNKNOWN che appare mentre npm install -g @anthropic-ai/claude-code sta sostituendo il binario ha la stessa causa di EACCES durante una reinstallazione e si cancella quando riprovi dopo che l'installazione finisce.

Claude Code avvia il servizio in background attraverso PowerShell in modo che il servizio sopravviva alla chiusura del terminale, usando PowerShell 7 quando è installato e Windows PowerShell 5.1 altrimenti. Quando nessun PowerShell può essere eseguito, Claude Code avvia il servizio direttamente invece, quindi una politica che blocca solo PowerShell non causa questo errore.

Prima della v2.1.212, Claude Code usava solo Windows PowerShell 5.1 per avviare il servizio, quindi qualsiasi macchina dove Group Policy bloccava PowerShell 5.1 falliva con Couldn't start the session — EUNKNOWN: unknown error, uv_spawn, anche con PowerShell 7 installato.

Cosa fare:

• Se il messaggio legge Couldn't start the session, aggiorna alla v2.1.212 o successiva. Su versioni precedenti puoi anche eseguire claude daemon run in un terminale separato per primo, quindi avviare di nuovo la sessione in background. Quel comando esegue il servizio in background in primo piano del terminale, quindi il servizio dura solo finché quel terminale rimane aperto.
• Se un npm install stava sostituendo il binario, aspetta che finisca, quindi avvia di nuovo la sessione in background
• Se l'errore appare su v2.1.212 o successiva mentre nessun npm install è in esecuzione, verifica con il tuo amministratore Windows se una politica di restrizione blocca l'eseguibile Claude Code
• Se il servizio in background si interrompe quando chiudi il terminale, Claude Code l'ha avviato senza PowerShell. Installa PowerShell 7, o chiedi al tuo amministratore di sbloccare PowerShell, in modo che il servizio possa sopravvivere al terminale.

EACCES quando si avvia una sessione in background

Claude Code non poteva eseguire il suo stesso binario per avviare il servizio in background che ospita le sessioni in background. Su un'installazione npm, questo di solito significa che npm install -g @anthropic-ai/claude-code stava sostituendo il binario in quel momento, sia che l'abbia eseguito tu che l'auto-updater. L'errore appare quando apri una sessione dalla vista agente:

Couldn't start the background service — spawn background service: EACCES: permission denied, posix_spawn '/usr/local/lib/node_modules/@anthropic-ai/claude-code/bin/claude'

Quando avvii una sessione con /background o claude --bg, lo stesso motivo appare all'interno di Couldn't reach the background service (...). Durante la stessa finestra di reinstallazione l'errore può nominare un altro codice invece, come ENOENT o ENOEXEC, o EUNKNOWN o EPERM su Windows; un EUNKNOWN che persiste attraverso i nuovi tentativi ha una causa diversa.

Su un'installazione npm, Claude Code aspetta che la reinstallazione finisca e riprova da solo: fino a dieci secondi, e fino a due minuti mentre un npm install di Claude Code è visibilmente ancora in esecuzione sulla macchina, che copre un altro processo Claude Code che scarica un aggiornamento. Quando l'installazione dura più di quella attesa, l'errore nomina l'aggiornamento invece del codice di errore nudo:

Claude Code is being updated by npm on this machine (still not runnable after 2 min, EACCES) — try again when the update finishes

Prima della v2.1.257, l'attesa si fermava a dieci secondi in ogni caso, quindi questo errore appariva mentre un altro processo Claude Code stava ancora scaricando un aggiornamento. Prima della v2.1.246, Claude Code falliva subito, senza aspettare.

Cosa fare:

• Aspetta alcuni secondi, quindi apri di nuovo la sessione o invia di nuovo. Quando il messaggio dice che Claude Code è in fase di aggiornamento, riprova dopo che l'aggiornamento finisce.
• Se l'errore persiste mentre nessun npm install è in esecuzione, il tuo utente non può eseguire il binario installato. Controlla i suoi permessi e quelli della sua directory, o reinstalla Claude Code.

Il servizio in background è uscito prima di diventare raggiungibile

Il processo che Claude Code ha avviato come servizio in background è uscito prima di accettare connessioni, quindi Claude Code non poteva aprire la tua sessione. Quando il servizio ha stampato un errore prima di uscire, il motivo tra parentesi fornisce il codice di uscita o il segnale e la prima riga che il servizio ha stampato, che nomina cosa l'ha fermato:

Couldn't reach the background service (background service exited before it became reachable (exit code N): <the service's first error line>) — run 'claude daemon status'

Quando apri una sessione dalla vista agente, lo stesso motivo segue Couldn't start the background service —. Quando il servizio non ha stampato nulla prima di uscire, il messaggio dice nothing on stderr invece.

Claude Code riporta l'errore con la riga di errore del servizio. Prima della v2.1.246, l'errore emergeva solo dopo un'attesa di 45 secondi, come background service did not become reachable within 45s, senza la riga di errore del servizio.

Due motivi citati hanno cause note:

• Error: claude native binary not installed.: un npm install stava sostituendo il binario Claude Code in quel momento, quindi il servizio ha eseguito il placeholder di npm invece. Riprova dopo che l'installazione finisce; se la riga persiste senza nessun install in esecuzione, completa l'npm install. Prima della v2.1.257, un auto-aggiornamento npm di macOS ha prodotto questo errore ad ogni avvio durante la finestra di installazione.
• nothing on stderr con codice di uscita 1, ad ogni avvio, su Windows: daemon.lock nomina un processo che Claude Code non può né segnalare né provare sia andato, quindi ogni nuovo servizio conclude che un altro lo tiene e esce. Un lock il cui scrittore Claude Code può provare sia andato viene sostituito da solo e non produce questo errore. Quando l'errore si ripete ad ogni avvio, elimina ~/.claude/daemon.lock, quindi apri di nuovo la sessione o invia di nuovo. Prima della v2.1.257, tale lock bloccava ogni avvio fino a quando non eliminavi il file.

Cosa fare:

• Se il messaggio cita una riga, correggi quello che nomina, quindi apri di nuovo la sessione o invia di nuovo. Il prossimo tentativo avvia di nuovo il servizio
• Esegui claude daemon status per controllare se un servizio è in esecuzione ora

La directory di lavoro non esiste più quando si avvia una sessione in background

La directory in cui hai avviato una sessione in background è stata rimossa mentre la sessione era in avvio. Claude Code non avvia la sessione, e il messaggio nomina la directory mancante:

Couldn't start a background session (working directory no longer exists or is not accessible: /tmp/demo)

Prima della v2.1.257, la sessione sembrava avviarsi e poi mostrava nella vista agente come una riga fallita con lo stesso motivo.

Prima della v2.1.281, questo messaggio appariva anche quando la directory era già scomparsa prima che avviassi la sessione. Quel caso riporta could not be resolved on disk.

Cosa fare:

• Ricrea la directory che il messaggio nomina, o invia da una directory che esiste, quindi riprova

Workspace non attendibile quando si invia una sessione in background

Hai avviato o riavviato una sessione in background in una directory a cui non hai concesso la fiducia, e la finestra di dialogo di fiducia del workspace non poteva apparire per chiedertelo. Claude Code non avvia la sessione:

Workspace not trusted. Run `claude` in /path/to/project once and accept the trust prompt, then retry.

Da un terminale nella directory della sessione stessa, lo stesso comando mostra la finestra di dialogo di fiducia invece e avvia la sessione una volta che accetti. Questo messaggio appare dove nessuna finestra di dialogo può, come in uno script, o quando riavvii una sessione da una directory diversa dalla sua.

Due varianti nominano una causa diversa:

• The home directory is trusted one session at a time: la directory della sessione è la tua directory home. Claude Code non salva mai la fiducia per la directory home, quindi accettare la finestra di dialogo lì in una sessione precedente non conta.
• <path> could not be resolved on disk: Claude Code non poteva trovare la directory della sessione su disco.

Prima della v2.1.286, su Windows, questo messaggio poteva apparire anche in una directory a cui avevi già concesso la fiducia, se il suo record di fiducia era stato salvato con il percorso in maiuscole/minuscole diverse. Aggiorna alla v2.1.286 o successiva.

Cosa fare:

• Esegui claude nella directory che il messaggio nomina e accetta la finestra di dialogo di fiducia, quindi esegui di nuovo il comando
• Per il messaggio della directory home, esegui il comando da un terminale nella tua directory home in modo che la finestra di dialogo possa apparire, o avvia la sessione da una directory di progetto invece
• Per il messaggio could not be resolved on disk, ricrea la directory, o avvia una nuova sessione da una directory che esiste

Errori del wrapper e dell'IDE

Questi errori provengono dal programma che ha avviato Claude Code per voi, come un'estensione IDE o un'applicazione Agent SDK, piuttosto che da Claude Code stesso.

Il processo Claude Code è uscito con codice N

Il processo claude sottostante è uscito con un codice diverso da zero. Il codice di uscita da solo non dice cosa è fallito: l'errore reale si trova nell'output del processo stesso, che il wrapper allega quando lo ha catturato e altrimenti mantiene nei suoi log.

Error: Claude Code process exited with code 1

Su Windows, la build nativa può uscire con codice 4294967295 subito dopo il completamento di un turno. Quando quell'uscita si verifica al confine di un turno, senza alcun messaggio in attesa e nessuna attività in background in esecuzione, l'estensione VS Code chiude la sessione silenziosamente invece di mostrare questo errore. Il vostro messaggio successivo riprende la conversazione.

Prima della v2.1.273, l'estensione mostrava l'errore per quell'uscita ad ogni confine di turno, anche se nulla era andato perso.

Cosa fare:

• In VS Code, seguite il collegamento View output logs mostrato con l'errore per vedere il guasto sottostante
• In un'applicazione Agent SDK, catturate l'errore intorno al vostro ciclo di messaggi. Le voci sotto CLI process exit coprono ciò che il vostro codice riceve in ogni linguaggio SDK.
• Eseguite claude in un terminale nello stesso progetto. Il guasto di solito si riproduce lì con il suo messaggio di errore reale, che potete quindi cercare su questa pagina.
• Eseguite claude doctor in un terminale per verificare l'installazione e la configurazione

Could not locate the Claude CLI on PATH

L'estensione VS Code mostra questo errore su Windows quando aprite Claude Code nel terminale integrato, la shell del terminale è PowerShell e l'estensione non riesce a trovare l'eseguibile claude installato su PATH. L'estensione si rifiuta di avviare Claude Code finché non trova il claude installato su PATH.

Failed to run Claude Code: Error: Could not locate the Claude CLI on PATH. Launching by name in a PowerShell terminal would run a 'claude' from the open folder instead of the installed CLI, so the launch was blocked. Make sure the Claude CLI's install directory is on your system PATH (not only your PowerShell profile), then restart VS Code and try again. VS Code reads PATH when it starts, so PATH changes take effect only after a restart.

Cosa fare:

• Aprite una nuova finestra PowerShell al di fuori di VS Code ed eseguite where.exe claude. Se non stampa un percorso, la CLI non è su PATH: aggiungete la sua directory di installazione seguendo Verify your PATH. Se stampa un percorso, la voce proviene dal vostro profilo PowerShell o da una modifica di PATH che VS Code non ha ancora raccolto; i prossimi due passaggi coprono questi casi.
• Impostate la voce PATH come variabile di ambiente utente o di sistema, non nel vostro profilo PowerShell. L'estensione non esegue il vostro profilo, quindi una modifica di PATH che vive solo lì non la raggiunge mai.
• Riavviate VS Code dopo aver modificato PATH. L'estensione controlla il PATH che VS Code ha catturato all'avvio, quindi una modifica di PATH ha effetto solo dopo un riavvio.

The connection to Claude Code ended before this message completed

L'estensione VS Code ha inviato il vostro messaggio al processo claude, e la connessione è terminata senza un errore prima che il processo lo riconoscesse o lo completasse. L'estensione non può dire se il messaggio è stato elaborato, quindi vi chiede di inviarlo di nuovo:

The connection to Claude Code ended before this message completed — it may not have been processed, so please send it again.

Cosa fare:

• Inviate il messaggio di nuovo. Il messaggio successivo avvia un nuovo processo claude che riprende la conversazione.
• Se si ripete, eseguite claude in un terminale nello stesso progetto. Un guasto che continua a terminare il processo di solito si riproduce lì con il suo messaggio di errore reale.

Avvisi e errori di Rewind

Questi messaggi provengono da un ripristino del codice /rewind. Restored the code, but skipped N files è un avviso che indica che Claude Code ha saltato alcuni percorsi. No files were restored è un errore che significa che non ha ripristinato nulla.

Restored the code, but skipped files

Un ripristino del codice /rewind ha saltato uno o più percorsi tracciati invece di scrivere o eliminare attraverso di essi. Claude Code salta un percorso quando:

• è, o è diventato, un symlink, hard link, o altro file non regolare
• la sua directory è cambiata dal checkpoint
• il suo backup non può essere letto in modo sicuro

I percorsi saltati mantengono i loro contenuti attuali. Prima della v2.1.216, /rewind scriveva e eliminava attraverso i link nei percorsi tracciati e non segnalava un ripristino parziale.

Restored the code, but skipped 2 files: the tracked path is (or became) a link or other non-regular file, its directory changed since the checkpoint, or its backup could not be safely read. Skipped files were left untouched — run with --debug for the paths.

Cosa fare:

• Identificare quali file sono stati saltati in modo da poter gestire ognuno con i passaggi seguenti. Il messaggio fornisce solo un conteggio; il log di debug in ~/.claude/debug/<session-id>.txt nomina ogni percorso saltato mentre il ripristino viene eseguito, quindi attivare la registrazione di debug con /debug prima del prossimo ripristino. Su macOS o Linux, è possibile invece trovare i link direttamente: find . -type l per i symlink e find . -type f -links +1 per i file con hard link.
• Se un file saltato è un link che hai creato intenzionalmente, come un file di configurazione gestito da un gestore dotfile o un file con hard link da strumenti come pnpm, il rewind ha lasciato i suoi contenuti intatti. Per annullare le modifiche della sessione ad esso, chiedi a Claude di invertire la modifica o modifica il file tu stesso
• Se non hai creato il link, ispeziona il percorso prima di fidarti dei suoi contenuti

No files were restored

Claude Code mostra questo messaggio quando ripristini il codice con /rewind e non riesce a ripristinare nessuno dei file in quel checkpoint. Per ogni file, il backup che Claude Code ha salvato prima di modificarlo è mancante, oppure Claude Code non ha potuto scrivere o eliminare il file.

Failed to restore the code:
No files were restored: 1 file failed (backup missing, or the file could not be updated)

Claude Code elimina i backup di una sessione nella retention sweep, per impostazione predefinita circa 30 giorni dopo l'ultimo salvataggio della sessione. Se riprendi una sessione dopo questo periodo, /rewind elenca ancora i suoi checkpoint, ma il ripristino a uno di essi può fallire con questo errore. Se il messaggio dice anche N paths were skipped for link safety, vedi Restored the code, but skipped files per quei percorsi.

Quando esegui il fork di una sessione, ad esempio con --fork-session o /branch, Claude Code copia i backup della sessione originale nel fork. Quando Claude Code non riesce a copiare un backup, ad esempio perché il disco è pieno, quel backup è mancante nel fork. Il ripristino a un checkpoint che ne ha bisogno può fallire con questo errore.

Cosa fare:

• Annulla le modifiche in un altro modo: chiedi a Claude di invertire le sue modifiche, o ripristina i file dal controllo versione. Quando i backup sono spariti, l'esecuzione di /rewind di nuovo fallisce allo stesso modo.
• Se Claude Code non ha potuto scrivere o eliminare un file, correggi ciò che blocca la scrittura, come i permessi dei file, quindi esegui /rewind di nuovo.
• Per mantenere i backup più a lungo nelle sessioni future, aumenta cleanupPeriodDays.

Prima della v2.1.260, Claude Code saltava silenziosamente i file i cui backup erano mancanti, e il rewind sembrava avere successo.

Avvisi di salvataggio della sessione

Claude Code mostra questi avvisi su una riga persistente sotto la casella di input quando non sta salvando la trascrizione della sessione. La sessione continua a funzionare comunque; gli avvisi indicano che la sessione potrebbe mancare da --resume in seguito.

I salvataggi della trascrizione stanno fallendo

Claude Code salva la trascrizione su disco mentre lavori, e i suoi salvataggi nel file della trascrizione stanno fallendo. Il messaggio nomina la causa con il codice di errore sottostante, ad esempio un disco pieno:

Transcript writes are failing (disk full — ENOSPC) · recent messages may not be saved for resume

L'avviso appare in diversi punti a seconda dell'errore:

• Al primo fallimento per condizioni che non si risolvono da sole: un disco pieno, un quota disco superata, un filesystem di sola lettura, un percorso che supera il limite di lunghezza del filesystem, o, su macOS e Linux, un errore di permesso
• Dopo fallimenti ripetuti che durano almeno un minuto per tutto il resto, inclusi errori di permesso su Windows, dove una scansione antivirus può far fallire un singolo salvataggio che poi riesce al nuovo tentativo

Prima della v2.1.217, Claude Code scartava i salvataggi falliti senza un avviso, e un successivo --resume mancante di messaggi recenti era il primo segno.

Cosa fare:

• Correggere la condizione che il codice di errore nomina: liberare spazio su disco per ENOSPC; aumentare o cancellare la quota per EDQUOT; ripristinare l'accesso in scrittura alla posizione della trascrizione per EACCES, EPERM, o EROFS
• L'avviso si cancella da solo al prossimo salvataggio riuscito; non è necessario riavviare
• I messaggi inviati mentre l'avviso era visualizzato potrebbero comunque mancare quando riprendi la sessione in seguito

Il salvataggio della trascrizione è disattivato perché CLAUDE\_CODE\_SKIP\_PROMPT\_HISTORY è impostato

Questa sessione è stata avviata con CLAUDE_CODE_SKIP_PROMPT_HISTORY impostato, quindi Claude Code non scrive alcuna trascrizione o cronologia dei prompt per essa:

Transcript saving is off — CLAUDE_CODE_SKIP_PROMPT_HISTORY is set · --resume will not find this session; if unintended, unset it and restart

La variabile è un'esclusione intenzionale per sessioni script effimere, ma può anche raggiungere una sessione attraverso un profilo shell, uno script wrapper, o un processo padre che l'ha esportata.

Cosa fare:

• Se hai impostato la variabile di proposito, non è necessaria alcuna azione; l'avviso conferma che la sessione non apparirà in --resume, --continue, o nella cronologia della freccia su
• Se non l'hai fatto, rimuovi la variabile dalla shell o dallo script che avvia claude, quindi avvia una nuova sessione. I messaggi della sessione corrente non vengono salvati retroattivamente.

Il salvataggio della trascrizione è disattivato a causa di un marcatore CLAUDE\_CODE\_CHILD\_SESSION ereditato

Claude Code imposta CLAUDE_CODE_CHILD_SESSION nei sottoprocessi che genera, e tratta una sessione interattiva che lo eredita come annidata: Claude Code non salva alcuna trascrizione per essa, quindi le sessioni che Claude stesso avvia non riempiono il tuo elenco --resume. Questo avviso significa che la tua sessione corrente ha ereditato il marcatore:

Transcript saving is off — inherited CLAUDE_CODE_CHILD_SESSION marker · restart with CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1 to keep future transcripts

L'avviso è previsto quando hai eseguito claude dall'interno di un'altra sessione Claude Code; segnala una classificazione errata quando il marcatore è trapelato attraverso un intermediario di lunga durata, ad esempio un terminale, una sessione screen, o un launcher che una sessione Claude Code ha originariamente avviato.

All'interno di tmux, Claude Code rileva un marcatore che è arrivato attraverso l'ambiente globale del server tmux e continua a salvare, quindi questo avviso non appare per quel caso.

Cosa fare:

• Se hai avviato questa sessione dall'interno di un'altra sessione Claude Code di proposito, non è necessaria alcuna azione
• Se questa è una sessione di primo livello, esci e riavvia con CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1 impostato. Il salvataggio si applica dal riavvio, quindi i messaggi inviati prima non vengono salvati.
• Per correggere i futuri avvii dallo stesso terminale o launcher, rimuovi CLAUDE_CODE_CHILD_SESSION dal suo ambiente

Avvisi di configurazione

Claude Code scrive la maggior parte di questi messaggi su stderr, non nella conversazione, e scrive la maggior parte di essi all'avvio. Una voce lo dice quando il suo messaggio appare altrove, ad esempio nel log di debug o come avviso di avvio nella vista della conversazione, o in un altro momento, ad esempio la riga diagnostica modello non riconosciuto al momento della richiesta.

Claude Code è uscito dopo un errore di interfaccia irrecuperabile

Claude Code stampa questo messaggio quando esce perché la sua interfaccia terminale ha riscontrato un errore da cui non può recuperare, in uno dei due renderer. La seconda frase appare solo quando l'errore si è verificato mentre il renderer fullscreen si stava avviando:

Claude Code exited after an unrecoverable interface error (<error>). It happened while the fullscreen renderer was starting, so the next launch will use the classic renderer (CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1 forces that any time).

Cosa fare:

• Avviare di nuovo Claude Code. Per riprendere la conversazione, eseguire claude --resume nella stessa directory.
• Se il messaggio nomina il renderer fullscreen, Fullscreen rendering dice cosa fa il prossimo avvio, che dipende da come avete attivato fullscreen, e come provare di nuovo fullscreen o mantenere il renderer classico.

Prima della v2.1.236, Claude Code usciva senza stampare un messaggio dopo questo tipo di errore.

Le descrizioni degli agenti superano il limite di 15.0k token

Claude Code mostra questo avviso come avviso di avvio nella vista della conversazione piuttosto che su stderr. Le descrizioni combinate dei vostri subagenti, ad eccezione di quelli incorporati, superano 15.000 token come Claude Code le stima. Ogni agente conta il suo nome più il suo frontmatter description. Claude Code carica ogni agente indipendentemente dal fatto che il totale superi il limite, quindi l'avviso non cambia cosa viene caricato.

Agent descriptions are over the 15.0k-token limit (~16.2k tokens) · ask Claude to trim agent descriptions in .claude/agents/

Cosa fare:

• Accorciare il frontmatter description dei vostri file di agente, o chiedere a Claude di tagliarli per voi.
• Rimuovere i file di agente che non usate più.

Una skill, un comando o un workflow non è stato caricato perché il suo nome è riservato

Una cartella skill, un frontmatter name, un file o una sottocartella in .claude/commands/, o un workflow salvato usa il nome anthropic-skills o un nome che inizia con anthropic-skills:. Claude Code riserva quel nome per le skills sincronizzate da claude.ai e non carica quell'elemento.

Claude Code mostra questo avviso come avviso di avvio nella vista della conversazione piuttosto che su stderr:

Not loaded: rename .claude/skills/anthropic-skills, then restart — its name uses "anthropic-skills", a name reserved for the skills synced from your claude.ai account

L'avviso nomina cosa cambiare per il primo elemento che ha rifiutato: una cartella o un file da rinominare, una riga name: da modificare, o un workflow da rinominare. Quando più di un elemento è stato rifiutato, l'avviso termina con un conteggio come · 2 more, e il log di debug nomina ognuno.

Cosa fare:

• Rinominare l'elemento che l'avviso nomina, o modificare la riga name: a cui punta, quindi riavviare la sessione.

Prima della v2.1.282, Claude Code caricava skills e comandi con questi nomi.

Lo spazio di lavoro non è stato considerato attendibile

Claude Code ha trovato regole permissions.allow o voci permissions.additionalDirectories nel .claude/settings.json o .claude/settings.local.json del progetto e non le ha applicate, perché le regole allow dalle impostazioni del progetto richiedono la fiducia dello spazio di lavoro. Il conteggio, il nome dell'impostazione e il file nominato nel messaggio variano con la vostra configurazione. Le regole deny e ask non sono interessate.

Ignoring 2 permissions.allow entries from .claude/settings.local.json: this workspace has not been trusted. Run Claude Code interactively here once and accept the trust dialog, or set projects["/Users/you/project"].hasTrustDialogAccepted: true in /Users/you/.claude.json.

Cosa fare:

• Eseguire claude nella directory e accettare la finestra di dialogo di fiducia. Project allow rules and workspace trust dice quale cartella copre tale accettazione.
• In modalità non interattiva con -p nessuna finestra di dialogo viene mostrata. Impostare la voce hasTrustDialogAccepted in ~/.claude.json usando la chiave projects esatta che il messaggio stampa.
• Se il messaggio nomina .claude/settings.local.json e avete avviato Claude Code al di fuori di un repository git o nella vostra home directory, aggiornare alla v2.1.200 o successiva. Le versioni 2.1.196 attraverso 2.1.199 hanno trattato il vostro .claude/settings.local.json come fornito dal repository in quegli spazi di lavoro. Sulla v2.1.207 e successiva, l'aggiornamento non è sufficiente al di fuori di un repository git se non avete considerato attendibile la cartella: determinare che una cartella non è all'interno di un repository esegue git, e Claude Code esegue quel controllo solo dopo che accettate la finestra di dialogo di fiducia, quindi usate il primo passaggio. La vostra home directory e qualsiasi altra configuration home sono esenti e non aspettano la finestra di dialogo. Vedere Project allow rules and workspace trust.

La directory di lavoro è un percorso di rete

Claude Code non aggiunge percorsi di rete come directory di lavoro. Cercare un percorso di rete può contattare l'host che nomina, e su Windows quel contatto può inviare all'host le vostre credenziali, quindi Claude Code rifiuta il percorso senza cercarlo. Vedete questo messaggio quando eseguite /add-dir con tale percorso, o come avviso all'avvio. Quando appare all'avvio, Claude Code si avvia senza quella directory.

\\server\share is a network path, which cannot be added as a working directory. On Windows, map the share to a drive letter and pass it at launch with --add-dir (a drive letter added mid-session does not yet carry remote-read trust).

I percorsi che Claude Code rifiuta in questo modo includono:

• Condivisioni UNC come \\server\share
• Percorsi di montaggio automatico come /net/<host>, a meno che non abbiate avviato Claude Code da una directory sotto il montaggio automatico di quell'host
• Percorsi locali che raggiungono una posizione di rete attraverso un collegamento simbolico o una giunzione

Le lettere di unità mappate e i percorsi \\wsl$ non contano come percorsi di rete.

Cosa fare:

• Su Windows, mappare la condivisione a una lettera di unità, ad esempio con net use Z: \\server\share, e passare l'unità all'avvio con claude --add-dir Z:\.
• Su macOS o Linux, montare la condivisione in un percorso locale e aggiungere quel percorso invece.
• Se il percorso è in permissions.additionalDirectories, rimuoverlo dal file di impostazioni che lo elenca.

Prima della v2.1.257, Claude Code accettava un percorso di rete raggiungibile come directory di lavoro.

Le impostazioni gestite da remoto non hanno potuto essere caricate

La vostra sessione è idonea per impostazioni gestite dal server, ma Claude Code non ha potuto recuperarle o non ha potuto applicare quello che il server ha restituito, quindi mostra questo avviso nelle sessioni interattive.

La causa tra parentesi nomina cosa è fallito, come network error, request timed out, o authentication rejected (401). La causa no setting in the server response could be applied as written significa che il server ha risposto ma nessuna delle impostazioni che ha restituito ha superato la validazione. Prima della v2.1.282, questa causa leggeva server returned invalid settings.

Il resto della riga dice quale politica la sessione esegue:

• Impostazioni memorizzate nella cache da un recupero precedente riuscito: Claude Code esegue la sessione su quella politica memorizzata nella cache, ad eccezione delle variabili di ambiente trattenute, e la riga legge using cached policy.
• Nessuna cache: Claude Code esegue la sessione senza impostazioni gestite dal server, e la riga legge no remote policy applied.

Cosa fare:

• Agire sulla causa che il messaggio nomina: per una causa di rete, verificare che questa macchina possa raggiungere api.anthropic.com; per una causa di autenticazione, controllare il vostro accesso con /status
• Per no setting in the server response could be applied as written, chiedere al vostro amministratore di correggere le impostazioni sul server
• Eseguire /status o claude doctor per la diagnostica completa

Prima della v2.1.248, Claude Code segnalava un recupero di impostazioni fallito solo nel log di debug.

Le impostazioni gestite non sono state approvate

Le impostazioni gestite dal server della vostra organizzazione includono impostazioni che necessitano della vostra approvazione, e avete rifiutato la finestra di dialogo di approvazione della sicurezza, quindi Claude Code esce senza applicarle:

Managed settings were not approved; exiting without applying them.

Cosa fare:

• Avviare di nuovo Claude Code e approvare la finestra di dialogo per continuare secondo le impostazioni della vostra organizzazione. Una finestra di dialogo rifiutata non viene ricordata, quindi appare di nuovo al prossimo avvio.
• Se siete incerti su un'impostazione che la finestra di dialogo elenca, chiedete a chi mantiene le impostazioni gestite della vostra organizzazione prima di approvare

Le impostazioni gestite bloccano il modello predefinito

La vostra organizzazione impostazioni gestite bloccano il modello a cui l'opzione Predefinito si risolve e ogni modello a cui potrebbe scendere. Una sessione che inizierebbe sull'opzione Predefinita esce all'avvio invece di eseguire un modello bloccato. Quale messaggio vedete dipende dall'impostazione che lo blocca. Quando un elenco deniedModels lo blocca, il messaggio legge:

Claude Code can't start: your organization's managed settings block the default model (claude-opus-5-5) in "deniedModels", and none of the models they allow can be used as the default instead. Ask your administrator to update "deniedModels" or "availableModels".

Quando un elenco availableModels con availableModelsMatch impostato a "exact" lo omette, il messaggio legge:

Claude Code can't start: your organization allows only the models listed in "availableModels", and none of them can be used as the default model (claude-opus-5-5 isn't listed). Ask your administrator to update "availableModels".

Cosa fare:

• Se amministrate le impostazioni, aggiungere un modello che i vostri utenti possono eseguire a availableModels, o restringere le voci deniedModels che bloccano ogni fallback. Block specific models or versions descrive come l'opzione Predefinito scende
• Se non le amministrate, inviare il messaggio al vostro amministratore. I vostri file di impostazioni non possono ampliare un elenco availableModels o deniedModels gestito

Le impostazioni gestite non consentono questo provider API

La vostra organizzazione impostazioni gestite impostano un elenco allowedProviders, e il provider API della sessione non è su di esso o la sessione usa un endpoint che non è fissato nel modo che quella voce richiede. Claude Code rifiuta all'avvio, prima di un accesso, o quando la sessione contatta successivamente l'API. Il messaggio inizia con i provider consentiti:

Your organization's managed settings allow Claude Code to use: Anthropic API, Amazon Bedrock.

Quando l'elenco è vuoto, il messaggio legge invece:

Your organization's managed settings allow Claude Code to use no API provider at all (allowedProviders is an empty list), so it cannot start on this machine.

Quando ogni voce non è riconosciuta, la parentetica legge invece (allowedProviders lists only unrecognized entries).

Cosa fare:

• Seguire i passaggi To continue: del messaggio
• Se amministrate le impostazioni, le righe del messaggio che iniziano con Admins: nominano la voce da aggiungere o il valore da fissare, e la voce allowedProviders dice quale blocco env della fonte può fissarlo

MCP server è bloccato dalla politica gestita aziendale

Avete selezionato Reconnect su un server in /mcp, o riattivato un server disabilitato lì, e un'impostazione che limita i server MCP blocca quel server. Claude Code rifiuta di connetterlo e mostra:

MCP server <name> is blocked by enterprise managed policy

Una qualsiasi di queste impostazioni può produrre il messaggio:

• Una voce deniedMcpServers che corrisponde al server, inclusa una nel vostro ~/.claude/settings.json o nel .claude/settings.json del progetto
• Un elenco allowedMcpServers che il server non corrisponde
• strictPluginOnlyCustomization con mcp bloccato, che blocca i server configurati in ~/.claude.json e .mcp.json
• disableClaudeAiConnectors, quando il server è un connettore claude.ai

Cosa fare:

• Controllare i vostri file di impostazioni utente e progetto per una di queste impostazioni e cambiarla o rimuoverla
• Se nessuna delle vostre impostazioni spiega il blocco, chiedete al vostro amministratore quale impostazione gestita blocca il server

Prima della v2.1.257, Reconnect e ri-abilitare in /mcp potevano connettere un server che un aggiornamento di politica mid-session bloccava.

Il documento delle impostazioni gestite non ha potuto essere analizzato

La vostra organizzazione distribuisce impostazioni gestite, e uno dei documenti distribuiti è presente ma non può essere analizzato come un oggetto JSON, quindi Claude Code esce con codice 1 all'avvio invece di eseguire senza la politica che il documento contiene. La riga nomina la fonte fallita prima del messaggio:

/Library/Application Support/ClaudeCode/managed-settings.json: Managed settings document could not be parsed as a JSON object; none of its settings are in effect. Fix or remove it.

La fonte è una di:

• Il percorso del file managed-settings.json o un file drop-in sotto managed-settings.d
• Il profilo delle preferenze gestite macOS, per-user managed preferences o device-level managed preferences
• Il valore del registro Windows, Registry: HKLM\SOFTWARE\Policies\ClaudeCode\Settings

Find entries Claude Code dropped elenca cosa rende ogni fonte non analizzabile.

Claude Code rifiuta di avviarsi anche quando un'altra fonte amministrativa fornisce una politica valida. Vedete questo errore nelle sessioni interattive, claude -p, sessioni Agent SDK, sessioni in background, e la maggior parte dei sottocomandi, claude doctor incluso. Il rifiuto fallisce chiuso di proposito: le impostazioni in un documento che Claude Code non può analizzare non possono essere applicate, e avviarsi comunque eseguirebbe sessioni senza i controlli dell'organizzazione.

Un problema di schema in un documento analizzabile non produce questo errore. Find entries Claude Code dropped copre cosa Claude Code fa con uno.

Quando una directory managed-settings.d/ esiste ma non può essere elencata, Claude Code segnala Managed settings drop-in directory could not be read: seguito dall'errore sottostante invece. Find entries Claude Code dropped copre quando un errore di lettura esce all'avvio.

Cosa fare:

• Se amministrate la macchina, correggere il documento nominato in modo che si analizzi come un oggetto JSON, o rimuovere il file, il profilo o il valore del registro. Un managed-settings.json vuoto conta come {} e non blocca l'avvio.
• Se non lo fate, chiedete al vostro amministratore di correggere il documento distribuito. Nulla nei vostri file di impostazioni causa o cancella questo errore.

Impossibile leggere le impostazioni della politica gestita

La vostra organizzazione distribuisce impostazioni gestite, e una delle fonti distribuite esiste ma non ha potuto essere letta, per un motivo come un errore di I/O piuttosto che il sistema operativo che nega la lettura. Senza un'altra fonte amministrativa che fornisce una politica, Claude Code esce all'avvio piuttosto che eseguire senza la politica che la fonte potrebbe contenere:

Unable to read managed policy settings.
This machine may require organization login enforcement, but the policy file failed to load.
Contact your administrator.

Detail: <source>: <reason>

Nello stesso stato, i flussi di accesso, le richieste API da una sessione che è già in esecuzione, e il server claude gateway sono rifiutati con una variante della prima riga che nomina allowedProviders.

Una lettura che il sistema operativo ha negato, come su un file solo root, non produce questa uscita: la sessione si avvia senza le politiche di quella fonte. Per una fonte che non può essere analizzata, Claude Code esce con un messaggio diverso che nomina la fonte.

Cosa fare:

• Se amministrate la macchina, correggere il problema che la riga Detail: nomina in modo che la fonte distribuita possa essere letta, o rimuovere la fonte
• Se non lo fate, inviare il messaggio al vostro amministratore. Nulla nei vostri file di impostazioni causa o cancella questo errore

Prima della v2.1.285, solo le sessioni accedute con credenziali claude.ai o Claude Console uscivano con questo messaggio, e una lettura che il sistema operativo ha negato lo produceva anche.

otelHeadersHelper non riuscito

Claude Code mostra questo avviso come una notifica nell'interfaccia terminale, una volta per sessione interattiva, quando lo script otelHeadersHelper fallisce o stampa output che non soddisfa i requisiti dello script.

Mentre lo script continua a fallire, le esportazioni falliscono e il vostro backend di telemetria non riceve nulla dalla sessione.

Il testo dopo See /status: dice cosa è fallito, come il codice di uscita dello script seguito dal suo output di errore:

otelHeadersHelper failed; telemetry is not being exported. See /status: exited 1: token service unreachable

Cosa fare:

• Eseguire /status per leggere il dettaglio del fallimento.
• Correggere lo script in modo che esca 0 entro 30 secondi e stampi un oggetto JSON di valori di intestazione stringa su stdout. Vedere requisiti dello script.
• Se la vostra organizzazione distribuisce lo script attraverso impostazioni gestite, chiedete a chi le mantiene di correggerlo.

In modalità non interattiva con -p, lo stesso fallimento appare su stderr come otelHeadersHelper failed (OpenTelemetry export headers unavailable): <error> invece.

headersHelper non eseguito

Claude Code ha connesso un server MCP con i suoi headers statici soli e ha saltato il headersHelper del server, perché l'helper è un comando shell e la cartella non ha fiducia salvata. Una cartella ottiene fiducia salvata quando impostate la sua voce in ~/.claude.json a mano o, al di fuori della vostra home directory, quando accettate la finestra di dialogo di fiducia per essa in una sessione interattiva. Vedere Trust a folder before its headersHelper runs per quali server questo controllo si applica.

Claude Code scrive questa riga in modalità non interattiva solo, una volta per server. In una sessione interattiva scrive lo stesso rifiuto al log di debug invece.

MCP server 'internal-api': headersHelper not run — this workspace has no persisted trust; accept the trust dialog here once interactively, or set projects["/Users/you/project"].hasTrustDialogAccepted in /Users/you/.claude.json.

La chiave projects che il messaggio stampa è la cartella Project allow rules and workspace trust dice Claude Code chiavi la fiducia su. Accettare la finestra di dialogo di fiducia per una cartella genitore non soddisfa il controllo, e una sessione -p o SDK non la soddisfa nemmeno.

Cosa fare:

• Eseguire claude nella cartella che il messaggio nomina, accettare la finestra di dialogo di fiducia, quindi eseguire di nuovo il vostro comando -p o SDK
• Impostare la voce hasTrustDialogAccepted in ~/.claude.json voi stessi, usando la chiave projects esatta che il messaggio stampa
• Se avete avviato la sessione nella vostra home directory, lavorare da una directory di progetto che avete considerato attendibile. Quando accettate la finestra di dialogo di fiducia nella vostra home directory, Claude Code mantiene quella fiducia per la sessione corrente solo.

Regola Tool(content) malformata

Una regola di permesso in uno dei vostri file di impostazioni non ha la forma Tool o Tool(content), ad esempio perché il testo segue la parentesi di chiusura o una delle parentesi manca. Claude Code salta la regola e la elenca nella finestra di dialogo delle impostazioni non valide quando una sessione interattiva si avvia, e nell'output di claude doctor:

Invalid permission rule "Bash(ls) x" was skipped: Malformed Tool(content) rule. Rules take the form Tool or Tool(content) and must end at the closing ")"; parentheses inside the content are literal

Cosa fare:

• Nel file di impostazioni elencato con il messaggio, riscrivere la regola in modo che termini alla sua parentesi di chiusura, ad esempio Bash(ls *) al posto di Bash(ls) x
• Lasciare le parentesi all'interno del contenuto come sono. Sono letterali, quindi una regola come Edit(./Finance (2024)/**) è valida senza escape

Prima della v2.1.260, Claude Code segnalava una regola con parentesi non abbinate come Mismatched parentheses.

Non è abbinato dai controlli di permesso dei file

Claude Code ha trovato una regola di permesso Write, NotebookEdit, MultiEdit, o Glob permission rule con un percorso in uno dei vostri file di impostazioni, in impostazioni gestite, o in un valore di flag --allowedTools, --disallowedTools, o --settings. Controlla i permessi dei file rispetto alle regole Edit e Read solo, quindi non consulta mai una regola di percorso che nomina uno degli altri strumenti di file. Mantiene la regola e non cambia nient'altro; l'avviso nomina la regola, la sua fonte tra parentesi, e la sostituzione da scrivere:

Permission deny rule (.claude/settings.json): Write(docs/**) is not matched by file permission checks — only Edit(path) rules are. Use Edit(docs/**) instead (Edit rules cover all file-editing tools).

Cosa fare:

• Sostituire le regole Write(path), NotebookEdit(path), e legacy MultiEdit(path) con Edit(path). Le regole Edit coprono tutti gli strumenti di modifica dei file.
• Ad eccezione di --allowedTools, dove Claude Code accetta una regola Glob senza avviso, sostituire le regole Glob(path) con Read(path).
• Correggere la regola alla fonte che l'avviso nomina tra parentesi: un percorso di file di impostazioni, o il flag stesso per --allowed-tools e --disallowed-tools. Un percorso claude-settings-<hash>.json che non esiste su disco rappresenta un valore --settings inline. Correggere il JSON che passate a quel flag.
• Lasciare sole le regole di nome di strumento nudo come Write o Glob. Claude Code le abbina a livello di tool level e non avvisa su di esse.
• Se la fonte legge managed policy settings, inoltrare l'avviso a chi mantiene le vostre impostazioni gestite, poiché non potete cancellarlo voi stessi.

In una sessione in background o con --output-format json o stream-json, Claude Code scrive l'avviso al log di debug invece di stderr, quindi l'output letto dalla macchina rimane pulito. Eseguire con --debug per catturarlo in ~/.claude/debug/<session-id>.txt. Prima della v2.1.210, Claude Code accettava queste regole senza un avviso.

Ha un carattere jolly prima del resto del comando

Claude Code ha trovato una regola allow Bash il cui * viene prima di una parola successiva che determina quale comando è, come Bash(git * main) o Bash(git -C * status *), in uno dei vostri file di impostazioni, in impostazioni gestite, o in un valore di flag --allowedTools o --settings. Il * corrisponde a qualsiasi testo, incluse le opzioni inserite in quella posizione: Bash(git * main) approva anche git -c core.fsmonitor=<script> diff main, dove -c fa eseguire a git un programma che il comando nomina. Wildcard patterns mostra le regole di corrispondenza.

L'avviso esiste in modo che possiate restringere una regola il cui carattere jolly è più ampio di quanto intendete. Claude Code mantiene la regola e non cambia nulla su come corrisponde; l'avviso nomina la regola e la sua fonte tra parentesi:

Permission allow rule (.claude/settings.json): Bash(git -C * status *) has a wildcard before the rest of the command, so it also matches any options inserted at that position and approves them without a prompt. For git, options such as -c and --exec-path can run arbitrary commands. Replace that * with the exact value you mean, or only use * after the subcommand (for example Bash(git status *)).

Cosa fare:

• Sostituire il * prima del sottocomando con il valore esatto che intendete: Bash(git checkout main) al posto di Bash(git * main).
• Spostare ogni * dopo il sottocomando: Bash(git status *) al posto di Bash(git -C * status *). Scrivere una regola per sottocomando che volete permettere.
• Correggere la regola alla fonte che l'avviso nomina tra parentesi: un percorso di file di impostazioni, o il flag --allowed-tools stesso. Un percorso claude-settings-<hash>.json che non esiste su disco rappresenta un valore --settings inline. Correggere il JSON che passate a quel flag.
• Se la fonte legge managed policy settings, inoltrare l'avviso a chi mantiene le vostre impostazioni gestite, poiché non potete cancellarlo voi stessi.

In una sessione in background o con --output-format json o stream-json, Claude Code scrive l'avviso al log di debug invece di stderr, quindi l'output letto dalla macchina rimane pulito. Eseguire con --debug per catturarlo in ~/.claude/debug/<session-id>.txt. Prima della v2.1.246, Claude Code accettava queste regole senza un avviso.

crossSessionInbound deve essere uno di accept, hold, refuse

Un file di impostazioni imposta crossSessionInbound a un valore che Claude Code non riconosce, come il typo "reject". La seconda frase dell'avviso dipende da quale file contiene il valore; in un file utente, progetto, locale, o --settings legge:

"crossSessionInbound" must be one of "accept", "hold", "refuse"; received "reject". This value was ignored; while it is present, cross-session messages are held for your approval instead of being delivered. Set it to one of the values above.

In impostazioni gestite, Claude Code tratta il valore non riconosciuto come refuse, il valore più restrittivo, e l'avviso dice che i messaggi cross-session vengono rifiutati fino a quando un amministratore non lo corregge. Per come l'hold si combina con i valori nei vostri altri file di impostazioni, vedere crossSessionInbound.

Cosa fare:

• Impostare la chiave a "accept", "hold", o "refuse", o rimuoverla
• Quando l'avviso nomina impostazioni gestite, chiedere all'amministratore di correggere il valore

Prima della v2.1.248, Claude Code ignorava un valore non riconosciuto senza avviso.

ANTHROPIC\_FOUNDRY\_RESOURCE deve essere il nome di una risorsa Foundry

Hai impostato ANTHROPIC_FOUNDRY_RESOURCE su qualcosa di diverso dal semplice nome di una risorsa Microsoft Foundry, ad esempio l'URL dell'endpoint o il suo nome host. Claude Code ha rifiutato il valore prima di inviare una richiesta. Il messaggio appare al posto della risposta di Claude, non come avviso di avvio:

API Error: ANTHROPIC_FOUNDRY_RESOURCE must be a Foundry resource name (2-64 letters, digits and hyphens, not starting or ending with a hyphen, such as my-resource), not a URL or host name. To use a full URL, set ANTHROPIC_FOUNDRY_BASE_URL instead.

Cosa fare:

• Imposta ANTHROPIC_FOUNDRY_RESOURCE sul solo nome della risorsa e riavvia Claude Code. Per l'endpoint https://my-resource.services.ai.azure.com/anthropic, il nome è my-resource.
• Per fornire invece l'URL completo dell'endpoint, imposta ANTHROPIC_FOUNDRY_BASE_URL sull'URL e rimuovi ANTHROPIC_FOUNDRY_RESOURCE, quindi riavvia Claude Code. Claude Code accetta solo una delle due variabili.

Il limite di 200K non è applicato

Avete impostato CLAUDE_CODE_DISABLE_1M_CONTEXT=1, che normalmente fa sì che auto-compaction mantenga le sessioni su modelli con contesto 1M a una finestra di 200K, ma nessuna soglia di compattazione limita questa sessione a o sotto 200K, quindi la conversazione può crescere oltre.

CLAUDE_CODE_DISABLE_1M_CONTEXT is set, but the 200K limit isn't enforced for <model>, so this session can grow past it. To enforce it, set CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000 (or the autoCompactWindow setting).

Claude Code applica il limite di 200K da solo per ogni modello che riconosce come avente una finestra nativa di 1M, e per ID di modello che non riconosce compatta alla finestra che assume. L'avviso appare quando altra configurazione sconfigge tale applicazione:

• L'ID del modello non è uno che Claude Code riconosce, come un alias di LLM gateway, e avete impostato CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1 o aumentato la finestra assunta oltre 200K con CLAUDE_CODE_MAX_CONTEXT_TOKENS. In questo caso il messaggio offre anche or update to a Claude Code version that recognizes <model> come rimedio.
• Un beta context-1m richiesto attraverso ANTHROPIC_BETAS o il flag --betas chiede ancora all'API la finestra 1M su un modello che accetta quel beta, mentre nulla compatta la sessione a 200K

Cosa fare:

• Impostare CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000, o l'impostazione autoCompactWindow a 200000, in modo che auto-compaction compatti al confine di 200K
• Se il messaggio nomina un ID di modello che questa versione non riconosce, eseguire claude update. Una versione che riconosce l'ID come modello con contesto 1M applica il limite senza ulteriore configurazione.
• Se volete che la sessione usi la finestra completa del modello invece, disimpostare CLAUDE_CODE_DISABLE_1M_CONTEXT; l'avviso segnala solo che il limite di 200K non è applicato

In una sessione in background o con --output-format json o stream-json, Claude Code scrive l'avviso al log di debug invece di stderr.

ID modello non riconosciuto su una richiesta

Claude Code ha inviato una richiesta per un ID di modello che la vostra versione di Claude Code non riconosce, e non ha trovato alcuna voce modelOverrides che mappa quell'ID a un modello che riconosce. Claude Code invia comunque la richiesta con l'ID come lo avete configurato, e non esce o cambia modelli.

[claude-code:unrecognized_model] {"model":"my-proxy-model","query_source":"sdk"}

In uno script o harness che legge stderr, abbinare il prefisso [claude-code:unrecognized_model]. Dopo il prefisso e uno spazio, Claude Code scrive un oggetto JSON su una riga. Claude Code può aggiungere campi ad esso in una versione successiva, quindi ignorare qualsiasi campo che non vi aspettate. Scrive almeno questi due:

• model: la stringa del modello come l'avete configurata
• query_source: il percorso della richiesta che ha usato il modello. Claude Code segnala sdk per un'esecuzione -p e un valore che inizia con agent: per un subagente.

Claude Code scrive la riga in uno di due posti, a seconda di come la eseguite:

• In modalità non interattiva con -p, Claude Code la scrive su stderr sotto ogni --output-format, in modo che possiate analizzare stdout senza filtrare la riga
• In una sessione interattiva o una sessione in background, Claude Code la scrive al log di debug invece; eseguire con --debug per catturarla in ~/.claude/debug/<session-id>.txt

Claude Code scrive la riga una volta per stringa di modello per processo. Scrive una riga separata per ogni ulteriore ID non riconosciuto, come uno che un subagente o funzionalità in background usa.

Claude Code non scrive la riga per ID di provider che risolve a un modello che riconosce, come ID Amazon Bedrock us.anthropic.claude-..., ID di Google Cloud's Agent Platform con un suffisso di versione @, e nomi di distribuzione Microsoft Foundry che contengono un ID di modello Claude. Claude Code controlla il modello dietro un ARN del profilo di inferenza dell'applicazione di Amazon Bedrock piuttosto che l'ARN stesso. Non scrive alcuna riga per un ARN che non può risolvere, come uno digitato male.

Cosa fare:

• Se avete impostato l'ID di proposito, come un alias di LLM gateway, aggiungere una voce modelOverrides al vostro file di impostazioni con l'ID come suo valore. Usare un ID di modello Anthropic come chiave, non un alias di famiglia come opus. Per my-proxy-model dalla riga di esempio, aggiungere questa voce:

  {
    "modelOverrides": {
      "claude-opus-4-6": "my-proxy-model"
    }
  }
  

  Claude Code allora tratta my-proxy-model come claude-opus-4-6 e smette di scrivere la riga.

• Se l'ID nomina un modello più nuovo della vostra versione di Claude Code, eseguire claude update

• Se l'ID è un typo, correggerlo in quale dei posti dove potete impostare un modello o variabili di alias lo contiene. Se query_source inizia con agent:, correggerlo dove impostate il modello del subagente invece.

Prima della v2.1.233, Claude Code non scriveva alcuna riga quando inviava una richiesta per un ID di modello che non riconosceva.

File di maschera sandbox stantii lasciati da una sessione uccisa

claude doctor stampa questo avviso nei suoi diagnostici, e /status elenca la stessa riga. Appare su Linux e WSL2 quando sandboxing è abilitato con isolamento del filesystem attivo.

Mentre un comando sandboxato esegue, la sandbox mantiene un rifiuto di scrittura su un file che non esiste ancora creando un segnaposto di lettura sola di 0 byte lì, e lo rimuove dopo. Una sessione uccisa prima che quella pulizia esegua, ad esempio da SIGKILL, lascia i segnaposti dietro. Sessioni successive li legano di sola lettura di nuovo ad ogni avvio, quindi una scrittura di impostazioni come salvare "Sì, e non chiedere di nuovo" fallisce dove uno siede.

- Stale sandbox mask files left by a killed session: /home/you/project/.claude/settings.local.json
  Fix: Remove each with `rm <path>` while no other Claude Code session is running in that project — a 0-byte read-only file where a settings file belongs makes "Yes, and don't ask again" fail to save, and the sandbox binds it read-only again on every start

Cosa fare:

• Chiudere qualsiasi altra sessione di Claude Code in esecuzione in quel progetto, quindi eliminare ogni file elencato con rm. L'avviso nomina fino a tre file e conta il resto, quindi rieseguire claude doctor dopo l'eliminazione fino a quando l'avviso non appare più. Un segnaposto che la sandbox di un'altra sessione sta ancora usando è una parte viva della protezione di scrittura di quella sessione
• Se una scelta di permesso che avete salvato con "Sì, e non chiedere di nuovo" non è rimasta, salvarla di nuovo dopo aver eliminato il segnaposto

Prima della v2.1.257, claude doctor non contrassegnava questi file; le versioni precedenti lasciano gli stessi segnaposti dietro quando una sessione viene uccisa.

Le risposte sembrano di qualità inferiore al solito

Se le risposte di Claude sembrano meno capaci di quanto ti aspetti ma non viene mostrato alcun errore, la causa è solitamente lo stato della conversazione piuttosto che il modello stesso. Claude Code non cambia silenziosamente le versioni del modello. Può passare a un modello di fallback in questi casi:

• Un --fallback-model configurato subentra dopo un errore di disponibilità, solo per quel turno, con un avviso nella trascrizione
• Un controllo di avvio di Amazon Bedrock o della piattaforma Agent di Google Cloud trova il tuo modello predefinito non disponibile, oppure il tuo account perde l'accesso ad esso durante la sessione
• Il fallback automatico del modello su Fable 5.1, Fable 5, Opus 5.5, Sonnet 5.5 e Opus 5 sposta la sessione al modello di fallback della categoria contrassegnata, quando quella categoria ne ha uno, e mostra un avviso nella trascrizione

Il controllo della selezione del modello di seguito cattura il secondo e il terzo caso; il primo appare come un avviso nella trascrizione piuttosto che come un cambio /model. La configurazione del modello spiega quando si applica ogni fallback.

Controlla prima questi elementi:

• Selezione del modello: esegui /model per confermare che sei sul modello che ti aspetti. Una scelta /model precedente o una variabile di ambiente ANTHROPIC_MODEL potrebbe averti messo su un modello più piccolo di quello che intendevi.
• Livello di sforzo: esegui /effort per controllare il livello di ragionamento attuale e aumentarlo per il debug difficile o il lavoro di progettazione. I valori predefiniti variano in base al modello, quindi controlla prima di assumere che sei al di sotto del massimo. Vedi Regola il livello di sforzo per i valori predefiniti per modello e il collegamento ultrathink.
• Pressione del contesto: esegui /context per vedere quanto è pieno il window. Se è vicino alla capacità, esegui /compact a un punto naturale o /clear per ricominciare da capo. Vedi Esplora la finestra di contesto per come auto-compact influisce sui turni precedenti.
• Istruzioni obsolete: file CLAUDE.md grandi o obsoleti e definizioni di strumenti MCP consumano contesto e possono indirizzare le risposte. Il controllo /doctor contrassegna i file di memoria sovradimensionati e le estensioni inutilizzate, e /context mostra l'utilizzo dei token degli strumenti MCP. Prima della v2.1.205, /doctor apriva una schermata di diagnostica che contrassegnava i file di memoria sovradimensionati e le definizioni dei subagent.

Quando una risposta va male, il rewind di solito funziona meglio che rispondere con correzioni. Premi Esc due volte o esegui /rewind per tornare indietro prima del turno sbagliato, quindi riformula il prompt con più specifiche. Correggere nel thread mantiene il tentativo sbagliato nel contesto, il che può ancorare le risposte successive ad esso. Vedi Checkpointing.

Se la qualità sembra ancora non corretta dopo aver controllato quanto sopra, esegui /feedback e descrivi cosa ti aspettavi rispetto a quello che hai ottenuto. Il feedback inviato in questo modo include la trascrizione della conversazione, che è il modo più veloce per Anthropic per diagnosticare una vera regressione. Vedi Segnala un errore se /feedback non è disponibile nel tuo ambiente.

Se Claude ti avverte di un sospetto prompt injection, o rifiuta una richiesta a causa di un sospetto injection, e il testo che l'avviso nomina è contesto che Claude Code aggiunge automaticamente alla conversazione piuttosto che contenuto di file o web, esegui claude update e riprova. Se l'avviso si ripete dopo l'aggiornamento, segnalalo piuttosto che incollare il contenuto contrassegnato di nuovo nel prompt. Prima della v2.1.201, Sonnet 5 rifiutava alcune richieste allo stesso modo.

Segnalare un errore

Per gli errori dei componenti non trattati in questa pagina, consultare la guida pertinente:

• Il server MCP non è riuscito a connettersi o autenticarsi: MCP
• Lo script hook non è riuscito o ha bloccato uno strumento: Debug hooks
• Permesso negato o errori del filesystem durante l'installazione: Risoluzione dei problemi di installazione e accesso

Se un errore non è elencato qui o la correzione suggerita non aiuta:

• Eseguire /feedback all'interno di Claude Code per inviare la trascrizione e una descrizione ad Anthropic. Il comando offre anche di aprire un problema GitHub precompilato. L'invio ad Anthropic richiede l'autenticazione. Su Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry e altri provider di terze parti, o quando non sono configurate credenziali Anthropic, /feedback salva un archivio locale che è possibile inviare al rappresentante dell'account Anthropic.
• Eseguire claude doctor dalla shell per una diagnostica di sola lettura dell'installazione, oppure eseguire il checkup /doctor all'interno di Claude Code per trovare e risolvere i problemi di configurazione
• Controllare status.claude.com per gli incidenti attivi
• Cercare i problemi esistenti su GitHub