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.

Trovare il vostro errore

Abbinate il messaggio che vedete 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.
• 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 thinking, 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 di 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 di 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 di 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 di 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 thinking 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 di strumento, o ne ha iniziato uno dopo aver finito il suo thinking, ma prima di finire la risposta. Claude Code non esegue nuovamente la richiesta, perché ciò potrebbe eseguire le stesse chiamate di strumento due volte. Mantiene ciò che Claude ha completato, esegue le chiamate di strumento 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 limite di velocità. 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 di strumento, o ne abbia iniziato uno dopo aver finito il suo thinking, 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 di strumento, o ne ha iniziato uno dopo aver finito il suo thinking, ma prima che Claude abbia finito la risposta, Claude Code mantiene ciò che Claude ha completato, continua il turno da qualsiasi chiamata di 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 di ambiente:

Errori del server

La maggior parte di questi errori proviene dal provider di inferenza: il servizio 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 vostro lato, come un account Amazon Bedrock che non può invocare il modello di classificazione 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 vostro prompt, dalle impostazioni o dall'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 il codice di stato e il suo nome standard. Prima della v2.1.281, il codice di stato veniva eliminato quando la pagina aveva un titolo e il markup grezzo della pagina veniva stampato quando non ne aveva uno.

Cosa fare:

• Controllate status.claude.com o la pagina di stato del provider indicata nel messaggio per gli incidenti attivi
• Aspettate un minuto, quindi inviate di nuovo il vostro messaggio. Il vostro messaggio originale è ancora nella conversazione, quindi per un prompt lungo potete digitare try again invece di incollare l'intera cosa.
• Se l'errore persiste senza alcun incidente pubblicato, eseguite /feedback in modo che Anthropic possa investigare con i dettagli della vostra richiesta. Vedete Report an error se /feedback non è disponibile nel vostro ambiente.

API Error: Repeated 529 Overloaded errors

L'API è temporaneamente al massimo 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 sopra.

Un 529 non è il vostro limite di utilizzo e non conta rispetto alla vostra quota.

Cosa fare:

• Controllate status.claude.com o la pagina di stato del provider indicata nel messaggio per gli avvisi di capacità

• Riprovate tra pochi minuti

• Eseguite /model e passate a un modello diverso per continuare a lavorare, poiché la capacità è tracciata per modello. Claude Code vi 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. Su modelli Fable il messaggio nomina Fable.

  In una sessione che l'app Claude Desktop esegue, come la scheda Code o Cowork, il messaggio legge Opus is experiencing high load. Switch to Sonnet. e cambiate i modelli con il selettore di modelli dell'app.

Request timed out

L'API non ha risposto prima della scadenza della connessione.

Request timed out

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

Cosa fare:

• Riprovate la richiesta
• Se la causa è una rete lenta o un proxy, aumentate API_TIMEOUT_MS come descritto in Automatic retries
• Se i timeout sono frequenti e la vostra rete è altrimenti sana, vedete Network and connection errors di seguito

No response from API

Claude Code ha inviato una richiesta di 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 aspettare il timeout di richiesta completo API_TIMEOUT_MS, 10 minuti per impostazione predefinita. Claude Code invia di nuovo la richiesta al massimo una volta, se il retry budget lo consente. Quando il nuovo tentativo rimane senza risposta, il turno termina con questo messaggio, che mostra quanto tempo ha aspettato ogni tentativo. Quando impostate CLAUDE_CODE_RETRY_WATCHDOG, il limite di un nuovo tentativo non si applica e Claude Code riprova secondo il budget descritto in Tune retry behavior.

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 l'attesa per le intestazioni di risposta del primo tentativo e l'attesa del nuovo tentativo separatamente:

• First attempt: CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS quando lo impostate su 1 o più, limitato tra 10 secondi e 30 minuti. Altrimenti Claude Code utilizza il timeout del watchdog a livello di byte elencato in Streaming idle watchdogs, quindi le variabili che cambiano quel timeout cambiano anche questa attesa. In entrambi i casi, Claude Code aggiunge un secondo per ogni 32KB del corpo della richiesta.
• Retry: 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 tiene la risposta fino al completamento della generazione. Su Amazon Bedrock, il nuovo tentativo utilizza la stessa scadenza del primo tentativo e il messaggio mostra una durata invece di due.

Nessuna attesa 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 inizia solo una volta che le intestazioni di risposta arrivano, quindi una risposta che smette di inviare byte dopo quello segue le stalled-stream rules invece di questa scadenza.

Cosa fare:

• Inviate di nuovo il vostro messaggio. Il vostro messaggio originale è ancora nella conversazione, quindi per un prompt lungo potete digitare try again invece di incollare l'intera cosa.
• Se si ripete, trattarlo come un network or proxy problem.
• Se un proxy o gateway sulla vostra rete tiene le risposte fino al completamento, aumentate API_TIMEOUT_MS in modo che il nuovo tentativo aspetti più a lungo. Su Amazon Bedrock, aumentate anche CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS.
• Se il primo tentativo continua a scadere e il nuovo tentativo ha successo, aumentate CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS in modo che il primo tentativo aspetti abbastanza a lungo.

Prima della v2.1.242, Claude Code aspettava il timeout di richiesta completo API_TIMEOUT_MS, 10 minuti per impostazione predefinita, prima di fallire una richiesta di streaming senza risposta. Prima della v2.1.261, il nuovo tentativo aspettava la stessa scadenza del primo tentativo e il messaggio non mostrava durate.

The response above may be incomplete

Una richiesta di streaming non è riuscita mentre la risposta era ancora in corso, dopo che Claude aveva completato un blocco di testo o una chiamata di strumento, o ne aveva iniziato uno dopo aver terminato il suo pensiero. L'invio di nuovo della richiesta potrebbe eseguire le stesse chiamate di strumento due volte, quindi Claude Code mantiene l'output che Claude ha completato e aggiunge questo avviso invece di scartare il turno. Quale variante vedete 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 del server di sovraccarico o 5xx a metà flusso. Questa variante richiede Claude Code v2.1.199 o successivo; prima di allora quel caso scartava l'output parziale e segnalava l'intero turno come errore.
• Connection lost mid-response: la connessione è stata interrotta. Vedete anche questa variante quando un proxy o gateway termina il corpo della risposta in modo pulito prima che la risposta sia terminata.
• Your computer went to sleep mid-response: Claude Code ha rilevato che il vostro computer si è addormentato mentre la risposta era in streaming. Una volta che il vostro computer si sveglia, Claude Code tratta la connessione come interrotta e smette di leggerla.
• Part of the response never arrived: un evento di flusso è stato perso tra l'API e Claude Code, quindi un evento successivo ha fatto riferimento a contenuto che non è mai arrivato. Prima della v2.1.281, questo caso ha terminato il turno con API Error: Content block not found.
• The response stream was malformed: un evento è arrivato per un blocco di contenuto che era già terminato, o un evento è arrivato danneggiato. Un evento danneggiato è uno i cui dati non sono JSON valido, il cui contenuto è mancante o il cui contenuto non corrisponde al tipo dell'evento. Prima della v2.1.284, l'errore grezzo del parser, come uno che inizia con API Error: JSON Parse error, appariva invece quando un evento con JSON non valido arrivava dopo che Claude aveva completato il suo pensiero, un blocco di testo o una chiamata di strumento.
• The response stopped arriving: la connessione è rimasta aperta ma ha smesso di consegnare dati, quindi il watchdog di inattività dello streaming l'ha interrotta. Prima della v2.1.222, Claude Code poteva anche segnalare questo errore su connessioni gateway raggiunte tramite ANTHROPIC_BASE_URL o ANTHROPIC_AWS_BASE_URL mentre i ping keep-alive del server stavano ancora arrivando, perché contava solo gli eventi di risposta analizzati lì; l'aggiornamento interrompe quei timeout spuri su quelle rotte. I gateway raggiunti tramite un URL di base del provider come ANTHROPIC_BEDROCK_BASE_URL non sono avvolti dal watchdog di byte; vedete Streaming idle watchdogs.

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

Quando un evento di flusso perso, duplicato o danneggiato arriva prima che Claude abbia iniziato qualsiasi testo o chiamata di strumento, non vedete questo avviso:

• Se Claude aveva completato solo il suo pensiero, Claude Code invia di nuovo la richiesta. Quando i flussi inviati di nuovo si rompono nello 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 nulla era stato completato, Claude Code invia di nuovo la richiesta senza streaming. Se avete disattivato quel fallback con CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK, il turno termina con API Error: Content block not found per un evento perso o API Error: Content block already closed per uno duplicato. Per un evento danneggiato con il fallback disattivato, il turno termina con API Error: Stream event unreadable o l'errore grezzo del parser.

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

• Più in alto nella risposta, Claude Code riprova l'errore o termina il turno con un errore diverso. Vedete Automatic retries.
• Quando uno di questi errori arriva dopo che Claude ha terminato la risposta, Claude Code mantiene la risposta completa e termina il turno normalmente, senza questo avviso. Prima della v2.1.222, Claude Code mostrava questo avviso quando la connessione veniva interrotta o si bloccava dopo il completamento della risposta e segnalava il turno come errore anche se la risposta era completa.
• In una non-interactive session, come una esecuzione -p, un'esecuzione Agent SDK o una cloud session, non dovete inviare continue voi stessi quando la risposta tagliata è nella conversazione principale e contiene testo ma nessuna chiamata di strumento: Claude Code mantiene l'output parziale e chiede a Claude di continuare da dove si è fermato, fino a tre volte di seguito. Vedete questo avviso per tale risposta solo una volta che Claude Code ha esaurito quelle continuazioni. Prima della v2.1.246, Claude Code terminava un turno non interattivo con questo avviso al primo taglio.
• In un subagent, indipendentemente dal fatto che la sessione sia interattiva o meno: quando la sua risposta tagliata contiene testo ma nessuna chiamata di strumento, Claude Code chiede al subagent di continuare. L'avviso diventa l'ultimo messaggio del subagent solo una volta che quelle continuazioni sono esaurite. Prima della v2.1.257, un subagent mostrava questo avviso al primo taglio.

Cosa fare:

• In una sessione interattiva, leggete la risposta che rimane sullo schermo: Claude Code mantiene ogni blocco che Claude ha completato prima dell'errore, ma scarta un blocco finale interrotto quando il turno termina, quindi le frasi o le chiamate di strumento finali potrebbero mancare. Rispondete con continue per far riprendere a Claude dal suo ultimo blocco completato.
• In non-interactive mode (-p):
  • Con l'output di testo predefinito, Claude Code stampa l'ultimo blocco di testo completato che ancora mantiene da prima nel turno, seguito da questo messaggio. Quando non ne mantiene nessuno, Claude Code stampa solo questo messaggio, ad esempio perché Claude Code ha compattato la conversazione a metà turno e ha cancellato quel testo. Prima della v2.1.219, Claude Code stampava solo questo messaggio nell'output di testo -p e scartava la risposta che aveva già prodotto.
  • Con --output-format json o stream-json, Claude Code segnala questo messaggio nel campo result.
  • Per continuare il turno una volta che la connessione è stabile, riprendete la sessione e inviate continue come descritto in Continue conversations.

Auto mode cannot determine the safety of an action

Il modello che auto mode utilizza per classificare le azioni non poteva produrre una decisione, quindi auto mode non ha approvato l'azione automaticamente. Il messaggio che vedete dipende da come il classificatore non è riuscito.

Le letture, le ricerche e le modifiche all'interno della vostra directory di lavoro saltano il classificatore, quindi continuano a funzionare in tutti questi casi.

Quando il modello di classificazione 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 può determinare la categoria di errore, la nomina 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, controllate la vostra connessione; vedete Unable to connect to API. Prima della v2.1.229, il messaggio non nominava mai una categoria e leggeva Wait briefly and then try this action again.

Quando nessuna categoria si adatta, il messaggio appare senza categoria tra parentesi; più di un errore produce quella forma. Su Amazon Bedrock, incluso l'Mantle endpoint, appare anche quando il vostro account AWS non può invocare il modello indicato nel messaggio e quel fallimento si ripete ad ogni nuovo tentativo fino a quando al vostro account non viene concesso l'accesso al modello.

Cosa fare:

• Riprovate dopo pochi secondi; Claude vede lo stesso messaggio e di solito riprova da solo. Un errore transitorio non è correlato all'auto mode eligibility; non dovete cambiare le impostazioni
• Se i nuovi tentativi continuano a fallire, continuate con attività di sola lettura e tornate all'azione bloccata in seguito
• Su Amazon Bedrock, se il messaggio ritorna ad ogni nuovo tentativo, controllate che il vostro account possa invocare il modello che nomina: per i modelli Amazon Bedrock standard, confermate che la vostra IAM policy consente di invocarlo; per gli ID modello Mantle, contattate il vostro team di account AWS

Quando una richiesta di classificazione non riesce perché il vostro token OAuth è scaduto o è stato ruotato da un'altra sessione, Claude Code aggiorna il token e riprova la richiesta una volta, quindi una scadenza di token di routine non emerge come questo messaggio. Prima della v2.1.216, un token scaduto o ruotato non riusciva ad ogni richiesta di classificazione e auto mode negava ogni azione controllata con questo messaggio fino a quando 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:

• Riprovate l'azione; questo di solito ha successo al tentativo successivo
• Eseguite claude --debug e ripetete l'azione per i dettagli nel registro di debug

Quando un controllo di sicurezza API separato ha bloccato la richiesta del classificatore a causa del contenuto della conversazione precedente:

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 dice a Claude che questo non è un giudizio che l'azione sia pericolosa e di continuare con altri compiti piuttosto che riprovare. Questi rifiuti non contano verso le auto mode's pause thresholds. In un'esecuzione -p non-interactive, Claude Code non interrompe l'esecuzione. Quello che Claude riceve dipende da dove ha richiesto l'azione:

• A un background subagent 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
• Ovunque, 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 contava questi rifiuti verso le soglie di pausa e restituiva lo stesso messaggio di rifiuto di un blocco di classificatore genuino.

Cosa fare:

• Questo non è un giudizio sulla vostra azione. Il contenuto già nella vostra conversazione ha attivato un filtro di sicurezza sull'API quando auto mode ha inviato la conversazione al classificatore
• Riprovare non aiuterà; lo stesso contenuto della conversazione attiverà di nuovo il filtro
• In una sessione interattiva, passate a una permission mode diversa in modo da poter approvare l'azione quando richiesto
• Iniziate una conversazione nuova senza il contenuto che attiva

Quando la conversazione è cresciuta 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)

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

• In una sessione interattiva, auto mode torna a un normale prompt di autorizzazione per quell'azione in modo da poter approvarla o negarla manualmente
• A un background subagent in un'esecuzione -p non-interactive 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'è alcun prompt a cui tornare, quindi l'azione non viene eseguita e l'esecuzione continua

Cosa fare:

• In una sessione interattiva, approvate o negate l'azione nel prompt che appare
• In una sessione interattiva, eseguite /compact per ridurre la dimensione della conversazione in modo che le azioni successive si adattino di nuovo alla finestra del classificatore

The server returned no safety verdict

Sotto server-side classifier review, auto mode nega un'azione quando il server non dà un verdetto per essa. Il rifiuto nomina una categoria tra parentesi quando Claude Code può determinarne una, 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 dice a Claude se un nuovo tentativo può aiutare. Prima di alcuni di questi rifiuti, Claude Code aspetta in modo che il prossimo tentativo di Claude non segua subito. Durante l'attesa in una sessione interattiva, lo spinner mostra Auto mode check unavailable con un conto alla rovescia, e premere Esc interrompe il turno.

Dopo dieci risposte di fila senza verdetto, auto mode 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 arresto appare in un posto diverso in ogni tipo di sessione:

• In una sessione interattiva, il messaggio appare come un avviso nella trascrizione e il turno termina
• In un'esecuzione -p non-interactive, l'esecuzione termina e segnala un errore di esecuzione. Con l'output di testo predefinito, il messaggio stampa su stderr.
• Quando un subagent ha raggiunto il limite, il subagent si ferma prima di finire, e Claude riceve quello che ha prodotto con una nota che auto mode l'ha fermato

Cosa fare:

• Inviate un altro messaggio per far riprovare a Claude. Il conteggio delle risposte ricomincia da capo.
• Se l'arresto si ripete e le vostre richieste passano attraverso un LLM gateway or proxy, controllate se taglia le risposte di streaming corte o le riscrive. Server-side classifier review dice quale comportamento del gateway causa rifiuti, e la gateway compatibility guide elenca cosa passare attraverso invariato.
• Impostate CLAUDE_CODE_AUTO_MODE_SERVER=0 prima di avviare Claude Code per utilizzare le sue richieste di classificatore. Prima della v2.1.281, Claude Code non leggeva la variabile su una connessione diretta a Anthropic API.
• Per approvare le azioni voi stessi, switch out of auto mode

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

Agent terminated early due to an API error

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

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

Cosa fare:

• Abbinate il dettaglio dell'errore dopo i due punti alla sua sezione su questa pagina, come Usage limits o Server errors, e seguite i passaggi di quella sezione
• Una volta che l'errore sottostante si risolve, chiedete a Claude di riprovare il compito o di resume the subagent

Quando un limite di velocità, sovraccarico o 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. Un subagent il cui unico output era chiamate di strumento riceve anche questo errore; nella v2.1.199 quella forma restituiva un risultato parziale vuoto. Vedete API errors in subagents.

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. Mentre attende, una riga in fondo alla sessione legge Usage limit reached · continuing automatically at 3:45pm · esc to cancel. Premi Esc a un prompt vuoto per annullare l'attesa. 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 significano che Claude Code non può provare la Vostra identità all'API. Eseguite /status in qualsiasi momento per vedere quale credenziale è attualmente attiva.

Non connesso

Nessuna credenziale valida è disponibile per questa sessione.

Not logged in · Please run /login

In una sessione che l'app Claude Desktop esegue, come la scheda Code o Cowork, il messaggio legge Authentication required · Sign in again to continue, e vi accedete di nuovo dall'app.

Cosa fare:

• Eseguite /login per autenticarvi con il Vostro abbonamento Claude o l'account Console
• Se vi aspettavate che una variabile d'ambiente vi autenticasse, confermate che ANTHROPIC_API_KEY sia impostata ed esportata nella shell dove avete lanciato claude
• Per CI o automazione dove il login interattivo non è possibile, configurate uno script apiKeyHelper che recuperi una chiave all'avvio
• Vedete Precedenza dell'autenticazione per capire quale credenziale Claude Code utilizza quando sono presenti più credenziali

Se vi viene chiesto di accedere ripetutamente, vedete Non connesso o token scaduto per i controlli dell'orologio di sistema e i passaggi di recupero dell'archiviazione delle credenziali di macOS.

Impossibile risolvere 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, -p e Agent SDK segnalano la stessa condizione di Non connesso e scrivono questa stringa solo nel loro log di debug, quindi se l'avete trovata lì, seguite quella voce invece.

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

Sulle versioni attuali l'errore significa che nessuna credenziale era disponibile al processo worker. Prima della v2.1.174, una sessione in background assegnata a un worker pre-inizializzato inattivo poteva fallire in questo modo anche quando le credenziali valide erano configurate. Prima della v2.1.176, anche una sessione cloud che era rimasta inattiva prima di essere rivendicata poteva farlo. Aggiornate per recuperare.

Cosa fare:

• Aggiornate alla v2.1.176 o successiva se questo appare in una sessione in background o cloud e le Vostre credenziali sono già configurate
• Confermate che ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN o le Vostre credenziali del provider cloud siano impostati nell'ambiente che avvia il worker, non solo nella Vostra shell interattiva
• Per Agent SDK, vedete configurazione dell'autenticazione nella guida rapida
• Eseguite /status in una sessione interattiva nello stesso ambiente per confermare quale fonte di credenziale si risolve

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 da ANTHROPIC_API_KEY prima di inviarla.

Invalid API key · Fix external API key

Quando il messaggio continua oltre 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 trasportare e ha fermato la richiesta prima di inviarla. Vedete Valore di intestazione di richiesta non valido per come leggere la descrizione e correggere il valore.

Cosa fare:

• Controllate gli errori di battitura e confermate che la chiave non sia stata revocata nella Console
• Nella stessa shell, eseguite env | grep ANTHROPIC, oppure in PowerShell Get-ChildItem Env:ANTHROPIC*. Strumenti come direnv, plugin shell dotenv e terminali IDE possono caricare una chiave obsoleta da un file .env nel Vostro progetto senza che la impostiate esplicitamente.
• Annullate l'impostazione di ANTHROPIC_API_KEY ed eseguite /login per utilizzare invece l'autenticazione dell'abbonamento
• Se la chiave proviene da uno script apiKeyHelper, eseguite lo script direttamente per confermare che stampi una chiave valida su stdout
• Eseguite /status per confermare quale fonte di credenziale Claude Code sta effettivamente utilizzando

Lo script apiKeyHelper non funziona

Claude Code ha eseguito il comando nella Vostra impostazione apiKeyHelper e non ha ottenuto una chiave indietro. Senza una, 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 è accaduto:

• Il comando è uscito con un errore o è scaduto
• Il comando non ha stampato nulla su stdout
• Il comando ha stampato qualcosa di diverso dalla chiave, come un banner di login o una riga di log. Il pannello mostra returned output that cannot be used as an API key e dice cosa c'è di sbagliato, senza ripetere l'output. Prima della v2.1.227, Claude Code inviava tutto ciò che il comando stampava, dopo aver tagliato gli spazi bianchi circostanti.

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, stderr trasporta anche il motivo specifico, con il prefisso apiKeyHelper failed:.

Claude Code riesegue lo script e ritenta la richiesta fino a due volte in più prima di mostrare questo messaggio, quindi l'errore emerge entro tre tentativi. Prima della v2.1.208, Claude Code spendeva l'intero budget di ripetizione reinviando la richiesta con la credenziale segnaposto e poi segnalava un errore di autenticazione generico 401 invece dell'errore dello script.

L'esecuzione di /login non aiuta qui: l'output dell'helper ha la precedenza su un login salvato finché l'impostazione è presente.

Cosa fare:

• Eseguite il comando configurato in apiKeyHelper direttamente nella Vostra shell per riprodurre l'errore
• Se il comando segnala una sessione scaduta, riauthenticate con il Vostro provider di credenziali, ad esempio accedendo di nuovo al Vostro SSO o vault di segreti
• Correggete il comando in modo che stampi solo la chiave su stdout, come un singolo token di ASCII stampabile fino a 16.384 caratteri, e uscite con codice 0. Vedete ruotare le credenziali con apiKeyHelper per una configurazione funzionante.
• Eseguite /status per vedere l'errore e confermare che apiKeyHelper sia la fonte di credenziale attiva. La riga apiKeyHelper mostra Failing con il dettaglio dell'ultimo errore, come il codice di uscita e l'output di errore del comando, e scompare dopo il prossimo esecuzione riuscita. Prima della v2.1.274, /status mostrava solo la fonte di credenziale, non l'errore.
• Ogni volta che il comando fallisce, il suo codice di uscita e l'output di errore appaiono anche in un pannello Authentication nel terminale. Prima della v2.1.212, il pannello era intitolato Cloud authentication.

Valore di intestazione di richiesta non valido

Un valore che Claude Code stava per inviare come intestazione di richiesta contiene un carattere che le intestazioni HTTP non possono trasportare: un'interruzione di riga, un byte NUL o un carattere sopra U+00FF, come una virgoletta ricurva o uno spazio di larghezza zero. Claude Code ferma la richiesta prima che qualsiasi cosa sia inviata e nomina la variabile o l'impostazione da correggere. La causa usuale è una credenziale incollata da un documento o chat che trasportava un carattere invisibile o un'interruzione di riga errata.

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

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 da dove proviene il valore errato:

• Invalid auth token: un token bearer da ANTHROPIC_AUTH_TOKEN o CLAUDE_CODE_OAUTH_TOKEN
• Invalid ANTHROPIC_CUSTOM_HEADERS: un nome o valore di intestazione che avete impostato in ANTHROPIC_CUSTOM_HEADERS. La descrizione conta quale coppia Name: Value è in colpa, come distinct header 2 of 3 parsed from ANTHROPIC_CUSTOM_HEADERS, senza ripetere il nome o il valore, poiché li avete scelti entrambi.
• Invalid request header from the environment: un valore che Claude Code copia in un'intestazione di richiesta da un'altra variabile d'ambiente, come CLAUDE_AGENT_SDK_CLIENT_APP. La descrizione nomina la variabile da correggere.

Claude Code segnala un ANTHROPIC_API_KEY errato catturato da questo controllo come Chiave API non valida, con la stessa descrizione finale. Segnala una credenziale /login salvata errata come Non connesso invece; eseguite /login per salvarne una nuova. L'output di uno script apiKeyHelper non raggiunge mai questo controllo: Claude Code lo convalida quando lo script viene eseguito e l'output che un'intestazione HTTP non può trasportare fallisce con Lo 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 da frasi fisse e conteggi di caratteri, quindi non include mai il valore stesso. Nomina il carattere offensivo solo quando è un carattere invisibile o tipografico ben noto, come un byte order mark, uno spazio di larghezza zero o una virgoletta ricurva, e segnala tutto il resto come a non-ASCII character.

Cosa fare:

• Reimpostate la variabile o l'impostazione che il messaggio nomina, riscrivendo i caratteri intorno alla posizione segnalata piuttosto che incollando dalla stessa fonte di nuovo
• Per ANTHROPIC_CUSTOM_HEADERS, mantenete una coppia Name: Value per riga e riscritte la coppia che il messaggio conta
• Eseguite /status per confermare quale fonte di credenziale è attiva

Questa organizzazione è stata disabilitata

Claude Code sta utilizzando un ANTHROPIC_API_KEY obsoleto da un'organizzazione Console disabilitata. Quando avete un login di abbonamento salvato, la chiave lo sostituisce.

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 Vostre credenziali salvate: la prima forma appare quando un /login memorizzato può subentrare dopo aver annullato l'impostazione della chiave, e la seconda quando la chiave è la Vostra unica credenziale.

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

Cosa fare:

• Annullate l'impostazione di ANTHROPIC_API_KEY nella shell corrente e rimuovetela dal Vostro profilo shell, quindi riavviate claude
• Se il messaggio dice Update or unset, non avete un login salvato su cui ricadere. Annullate l'impostazione della chiave ed eseguite /login, oppure sostituite la chiave con una da un'organizzazione Console attiva.
• Eseguite /status in seguito per confermare che la credenziale attiva sia il Vostro abbonamento
• Se nessuna variabile d'ambiente è impostata e l'errore persiste, contattate il supporto o accedete con un account diverso.

La Vostra organizzazione ha disabilitato l'autenticazione con chiave API

Questo messaggio richiede Claude Code v2.1.169 o successiva. L'amministratore dell'organizzazione Console ha disattivato l'autenticazione con chiave API, quindi l'API rifiuta la chiave che Claude Code sta inviando. Il suggerimento di recupero dopo il · varia a seconda di dove proviene la 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 appare in una sessione che l'app Claude Desktop esegue, come la scheda Code o Cowork, dove vi accedete di nuovo dall'app.

Le variabili d'ambiente e apiKeyHelper hanno la precedenza su /login, quindi eseguire /login da solo non aiuta mentre uno dei due sta ancora fornendo una chiave. Vedete Precedenza dell'autenticazione.

Cosa fare:

• Se il messaggio nomina ANTHROPIC_API_KEY, annullate l'impostazione nella shell corrente e rimuovetela dal Vostro profilo shell o file .env, quindi riavviate claude
• Se il messaggio nomina apiKeyHelper, rimuovete l'impostazione apiKeyHelper dal Vostro settings.json
• Eseguite /login per accedere con il Vostro account claude.ai
• Eseguite /status in seguito per confermare che la credenziale attiva sia il Vostro abbonamento piuttosto che una chiave API
• Se avete bisogno dell'autenticazione con chiave API per l'automazione, chiedete all'amministratore dell'organizzazione di riattivarla nella Console

La Vostra organizzazione ha disabilitato l'accesso all'abbonamento Claude

La Vostra organizzazione Claude non consente l'accesso a Claude Code con un login di abbonamento. L'esecuzione di /login di nuovo 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

Questa è un'impostazione dell'organizzazione lato server, quindi non può essere ignorata dalle impostazioni locali, dalle variabili d'ambiente o dai flag CLI.

Agent SDK e la modalità non interattiva -p presentano questo come il codice di errore oauth_org_not_allowed.

Cosa fare:

• Chiedete al Vostro amministratore di abilitare l'accesso a Claude Code per la Vostra organizzazione
• Autenticate con una chiave API Console invece del Vostro abbonamento. Vedete Autenticazione Claude Console per la configurazione.
• Se siete l'amministratore e non vedete un'opzione per abilitare l'accesso, contattate il supporto Anthropic

Le routine sono disabilitate dalla politica dell'organizzazione

Un Proprietario nella Vostra organizzazione Team o Enterprise ha disattivato le routine a livello di organizzazione. L'errore appare quando tentate di creare o eseguire una routine, ad esempio dall'interfaccia utente 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.

Questa è un'impostazione lato server, quindi non può essere ignorata dalle impostazioni locali, dalle variabili d'ambiente o dai flag CLI.

Cosa fare:

• Chiedete a un Proprietario nella Vostra organizzazione di abilitare l'interruttore Routines su claude.ai/admin-settings/claude-code
• Per lavoro programmato una tantum che non richiede routine a livello di organizzazione, vedete attività programmate

Remote Control richiede l'API Anthropic

La sessione non sta parlando direttamente all'API Anthropic, che Remote Control richiede.

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 solo la prima frase. A seconda della causa, il messaggio nomina:

• 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 proxy, anche quando vi accedete con claude.ai; prima della v2.1.196, un URL di base personalizzato non bloccava Remote Control
• ANTHROPIC_UNIX_SOCKET impostato, quindi la sessione invia le sue richieste attraverso un socket locale piuttosto che a api.anthropic.com
• Un accesso gateway cloud aziendale effettuato tramite /login, che non supporta Remote Control e non ha alcuna variabile da annullare

Cosa fare:

• Annullate l'impostazione della variabile che il messaggio nomina, come CLAUDE_CODE_USE_BEDROCK o ANTHROPIC_BASE_URL, e riavviate la sessione, oppure avviate Remote Control da una sessione che parla direttamente all'API Anthropic
• Se la variabile non è impostata nella Vostra shell, controllate la chiave env nei Vostri file di impostazioni, che applica le variabili d'ambiente a ogni sessione
• Per questo e gli altri messaggi di avvio di Remote Control, vedete Risolvere i problemi di Remote Control

Remote Control non ha potuto aggiornare il Vostro login

Claude Code esegue una connessione Remote Control dal vivo su credenziali di breve durata che ottiene e rinnova utilizzando il Vostro login claude.ai salvato. Quando claude.ai smette di accettare quel login, o Claude Code non ha più alcun login salvato, Claude Code ferma Remote Control e ha bisogno che vi accediate di nuovo. Uno qualsiasi dei due errori può accadere mentre Claude Code sta ancora connettendosi o più tardi, quando rinnova le credenziali.

Quando Claude Code chiede al servizio di login di aggiornare il Vostro login salvato e non riceve risposta, mantiene Remote Control in esecuzione e ritenta l'aggiornamento mentre la credenziale corrente della connessione è ancora valida. Un aggiornamento non riceve risposta quando Claude Code non può raggiungere il servizio di login, la richiesta scade o il servizio fallisce senza rifiutare il Vostro login. Se il servizio di login non sta ancora rispondendo quando quella credenziale scade, Claude Code ferma Remote Control e segnala OAuth token refresh failed.

Quando Claude Code ferma Remote Control, mostra il motivo in un avviso e in una riga di trascrizione che inizia con Remote Control disconnected. La Vostra sessione locale continua a funzionare senza Remote Control. Questa sezione copre 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 nomina la causa nel mezzo del messaggio:

• Claude.ai login expired e Claude.ai login was rejected: claude.ai non accetta più il Vostro token di login salvato, perché è scaduto o è stato revocato
• OAuth token unavailable: Claude Code non aveva alcun token di login salvato quando la credenziale della connessione è scaduta per il rinnovo
• OAuth token refresh failed: claude.ai ha rifiutato il Vostro token di login salvato mentre Claude Code stava riconnettendosi e l'aggiornamento del token non ha prodotto uno nuovo
• JWT refresh failed: no OAuth token: Claude Code non ha trovato alcun token di login salvato per rinnovare
• Signed out of Claude: vi siete disconnessi su questa macchina, ad esempio eseguendo /logout in un altro terminale, quindi Claude Code non ha alcun login salvato rimasto per rinnovare la connessione

Cosa fare:

• Eseguite /login per accedere di nuovo
• Eseguite /remote-control per riconnettere la sessione. I messaggi che terminano con run /login to restore Remote Control non hanno bisogno di questo passaggio: Claude Code si riconnette automaticamente una volta che vi siete acceduti.

Prima della v2.1.224, OAuth token refresh failed — run /login to re-authenticate leggeva OAuth token refresh failed — re-authenticate, then re-enable Remote Control, e JWT refresh failed: no OAuth token — run /login leggeva 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 dicono Signed out of Claude come JWT refresh failed: no OAuth token — run /login, e fermava Remote Control con Claude.ai login expired — run /login to restore Remote Control non appena un aggiornamento di login non riceveva risposta.

Remote Control si è fermato perché l'account connesso è cambiato

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

Una sessione Remote Control che avete avviato mentre eravate connessi tramite /login appartiene all'account claude.ai e all'organizzazione che erano connessi al 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 ferma la sessione Remote Control non appena claude.ai conferma che l'account o l'organizzazione è cambiato. La Vostra sessione locale continua a funzionare senza Remote Control.

Cosa fare:

• Eseguite /remote-control per avviare una nuova sessione Remote Control con l'account o l'organizzazione corrente
• Per tornare indietro, eseguite /login e accedete di nuovo all'account o all'organizzazione precedente. Quindi eseguite /remote-control.

Prima della v2.1.234, Claude Code non notava quando vi passavate a un account o un'organizzazione diversa al di fuori della sessione Claude Code. Claude Code manteneva la sessione Remote Control connessa fino a quando una richiesta successiva al server Remote Control non falliva con Remote Control server rejected the request (HTTP 404). Quel fallimento potrebbe arrivare ore dopo il cambio.

Remote Control si è fermato perché l'app che esegue la sessione si è disconnessa o ha cambiato account

Quando l'app desktop Claude o un IDE ospita la Vostra sessione, Claude Code ottiene il Vostro token di login da quell'app piuttosto che da /login. Quando claude.ai rifiuta quel token, Claude Code chiede all'app uno nuovo. Se l'app risponde che è disconnessa, o che è ora connessa a 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 Vostra sessione locale continua a funzionare senza Remote Control.

Cosa fare:

• Se l'app è disconnessa, accedete di nuovo, quindi riattivate Remote Control nell'app
• Se l'app ha cambiato account, Claude Code non può continuare la sessione terminata con il nuovo account. Avviate una nuova sessione Remote Control con quell'account.

Prima della v2.1.238, Claude Code inviava all'app i messaggi run /login elencati sotto Remote Control non ha potuto aggiornare il Vostro login in entrambi i casi.

Token OAuth revocato o scaduto

Il Vostro login salvato non è più valido. Un token revocato significa che vi siete disconnessi ovunque o un amministratore ha rimosso l'accesso; un token scaduto significa che l'aggiornamento automatico è fallito a metà sessione.

Entrambi i messaggi segnalano un rifiuto che l'API ha restituito per una richiesta che Claude Code ha inviato. Quando il login salvato è già stato cancellato dopo un aggiornamento fallito, vedete Login scaduto invece. Se vi autenticate con un token di lunga durata in CLAUDE_CODE_OAUTH_TOKEN, vedete 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 ...

Cosa fare:

• Eseguite /login per accedere di nuovo
• Se vi autenticate con la variabile d'ambiente CLAUDE_CODE_OAUTH_TOKEN, Claude Code continua a inviare il valore che avete impostato dopo che una richiesta fallisce con un 401, piuttosto che passare al token di un login salvato. /status mostra questa credenziale come una riga Auth token che legge CLAUDE_CODE_OAUTH_TOKEN. Generare un token fresco con claude setup-token e riavviare con esso, oppure annullate l'impostazione della variabile ed eseguite /login. Prima della v2.1.225, Claude Code poteva sostituire il valore della variabile a metà sessione con il token di accesso di breve durata da un login salvato, e la sessione falliva di nuovo con errori 401 una volta che quel token scadeva.
• Per i prompt ripetuti di accesso tra i lanci, vedete i controlli dell'orologio di sistema e i passaggi di recupero dell'archiviazione delle credenziali di macOS in Risoluzione dei problemi
• Per altri errori inclusi 403 Forbidden e problemi del browser OAuth, vedete Login e autenticazione

API Error: 401 Credenziali di autenticazione non valide

L'API ha riconosciuto il formato della Vostra credenziale ma ha rifiutato l'account o l'organizzazione dietro di essa. Anthropic restituisce questo messaggio quando una credenziale è stata revocata di recente, quando un'organizzazione è stata disabilitata o ha rimosso il Vostro accesso, o quando l'account stesso è stato disattivato, quindi un token scaduto non è la causa. La credenziale può essere il Vostro login salvato o un ANTHROPIC_API_KEY approvato, e la correzione differisce, quindi iniziate eseguendo /status per vedere quale è attivo.

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

Cosa fare:

• Se /status mostra una riga API key che non è contrassegnata come non in uso, un ANTHROPIC_API_KEY approvato è la credenziale attiva e ha la precedenza sul Vostro login, quindi /login non lo sostituisce. Ruotate la chiave nella Console Claude, oppure ricadete sul Vostro abbonamento eseguendo unset ANTHROPIC_API_KEY, oppure in PowerShell Remove-Item Env:ANTHROPIC_API_KEY.
• Se /status mostra solo il Vostro login, eseguite /login una volta. Se la credenziale è stata revocata, un login fresco la sostituisce.
• Se lo stesso messaggio ritorna per lo stesso account di login, l'account o l'organizzazione non è più attivo. Controllate l'account e l'organizzazione che /status segnala, e chiedete al Vostro amministratore dell'organizzazione di ripristinare l'accesso.
• Se ANTHROPIC_BASE_URL punta a un gateway LLM, il testo dopo 401 è il messaggio del Vostro gateway piuttosto che di Anthropic, e /login non lo cambia. Correggete invece la credenziale che il Vostro gateway si aspetta.

Login scaduto

Claude Code ha tentato di rinnovare il Vostro login claude.ai salvato e il servizio OAuth ha rifiutato il token di aggiornamento memorizzato, quindi Claude Code ha cancellato le credenziali salvate. Dopo di che, ogni richiesta di modello si ferma 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 del modello con qualsiasi credenziale rimanesse nell'ambiente, e ogni modello falliva con C'è un problema con il modello selezionato o un 401 invece di un prompt per accedere.

Login expired · Please run /login

In modalità non interattiva (-p) e Agent SDK, il messaggio legge come segue, e il codice di errore strutturato è authentication_failed:

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

Questo non è lo stesso stato di Token OAuth revocato o scaduto. Quei messaggi segnalano un rifiuto che l'API ha restituito. Claude Code stesso produce Login expired per un login che ha già fallito di rinnovare, quindi non invia alcuna richiesta. Quando il rinnovo fallisce perché l'account stesso è sospeso piuttosto che il login essere obsoleto, Claude Code mostra Il Vostro account è in sospeso invece.

Le sessioni autenticate con una chiave API, CLAUDE_CODE_OAUTH_TOKEN o un provider di terze parti non utilizzano il login salvato e non vedono mai questo messaggio.

Potete controllare questo stato prima che una richiesta fallisca: /status mostra una riga Login che legge Expired — log in again, più l'organizzazione e l'email che ha salvato per il login scaduto. La riga appare solo quando il login salvato è la Vostra credenziale attiva e non può più essere rinnovato. Le sessioni autenticate in un altro modo non mostrano la riga, anche se un login scaduto rimane salvato. Prima della v2.1.210, /status non dava alcuna indicazione in questo stato che un login fosse mai esistito, perché la credenziale cancellata non le lasciava nulla da segnalare.

Cosa fare:

• Eseguite /login per accedere di nuovo. Riprovare senza accedere mostra lo stesso messaggio su ogni richiesta.
• In modalità non interattiva, eseguite claude nello stesso ambiente, completate /login, quindi rieseguite il Vostro comando. Per l'automazione che non può accedere in modo interattivo, autenticate con ANTHROPIC_API_KEY o generate un token di lunga durata con claude setup-token.
• Se l'accesso continua a fallire, vedete Login e autenticazione

Impossibile aggiornare il Vostro login perché un altro processo Claude Code lo sta aggiornando

Questo messaggio non significa che il Vostro login sia stato rifiutato. Il Vostro login claude.ai salvato era scaduto e aveva bisogno di rinnovamento. Un altro processo Claude Code sulla stessa macchina teneva il blocco di aggiornamento condiviso, o è uscito e lo ha lasciato dietro, e l'aggiornamento non ha fatto progressi mentre questa sessione aspettava. Claude Code ferma 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 Agent SDK, il messaggio legge come segue, 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, CLAUDE_CODE_OAUTH_TOKEN o un provider di terze parti non utilizzano il login salvato e non vedono mai questo messaggio.

Cosa fare:

• Riprovate tra un minuto. Se un altro processo completa l'aggiornamento per primo, questa sessione utilizza il login rinnovato.
• Se il messaggio continua a ritornare, chiudete altri processi e finestre Claude Code, quindi riprovate.
• Se ritorna senza alcun altro processo Claude Code in esecuzione, eseguite /login. L'accesso di nuovo non aspetta il blocco di aggiornamento.

Impossibile salvare il Vostro login

Vi siete acceduti con claude.ai, ma Claude Code non ha potuto salvare il login nel suo archivio di credenziali, quindi l'accesso non è stato completato. Su macOS questo può accadere quando il keychain di login si blocca, ad esempio al sonno o inattività, dopo che Claude Code ha già letto o salvato credenziali in esso 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 appare su macOS e la seconda ovunque. Un errore transitorio dell'archivio di credenziali, come un timeout o un archivio illeggibile, produce lo stesso messaggio.

Cosa fare:

• Su macOS, sbloccare il keychain di login, quindi eseguire /login di nuovo
• Su altre piattaforme, eseguire /login di nuovo
• Se il login ancora non si salva, vedete Non connesso o token scaduto per il comando di sblocco del keychain e altri passaggi di recupero dell'archiviazione delle credenziali

Failed to start OAuth callback server

Quando /login, claude auth login, o claude setup-token vi accede attraverso il browser, Claude Code apre una porta in ascolto su 127.0.0.1 in modo che il Vostro browser possa restituire il risultato dell'accesso a esso. Questo messaggio significa che Claude Code non ha potuto aprire quella porta, e l'accesso si ferma prima che una finestra del browser o un URL di login appaia:

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

Se il Vostro messaggio termina con Is port 0 in use?, il tentativo di ascoltare sull'indirizzo loopback IPv4 127.0.0.1 è fallito completamente. Poiché l'errore accade prima che esista un URL di login, il flusso Paste code here if prompted non è disponibile come soluzione alternativa.

Cosa fare:

• Per accedere subito senza il listener locale: se utilizzate un abbonamento claude.ai, eseguite claude setup-token su una macchina dove l'accesso funziona e impostate il token che stampa come CLAUDE_CODE_OAUTH_TOKEN su questa macchina. Altrimenti impostate ANTHROPIC_API_KEY a una chiave dalla Console Claude. Precedenza dell'autenticazione spiega come Claude Code sceglie tra le credenziali.
• Per utilizzare l'accesso del browser su questa macchina invece, Claude Code deve essere in grado di ascoltare su 127.0.0.1. Se viene eseguito all'interno di una sandbox, controllate che la politica della sandbox consenta l'ascolto su porte locali, quindi eseguite /login di nuovo. Se dovrebbe essere in grado di farlo e ancora fallisce, eseguite /feedback in modo che il rapporto includa i dettagli del Vostro ambiente.

Claude login non accettato

Avete tentato di avviare una sessione cloud, e il server ha rifiutato di crearla con un 401: non ha accettato il login Claude che questa macchina ha inviato, di solito perché il login è scaduto o è stato revocato.

La prima parte della riga è il motivo del server quando ne fornisce uno. Altrimenti la riga legge:

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

Cosa fare:

• Eseguite /login, completate l'accesso, quindi avviate di nuovo la sessione

Artifacts hanno bisogno di un login claude.ai

Claude Code ha rifiutato una pubblicazione o lettura di artifact perché la sessione non ha alcun login claude.ai che possa utilizzare per gli artifact.

Ogni forma del messaggio inizia con le stesse parole, seguita da un rimedio che dipende da come la Vostra sessione si autentica. Senza alcuna credenziale in competizione legge:

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:

• Eseguite /login e selezionate Claude account with subscription. L'opzione Anthropic Console account non fornisce credenziali claude.ai.
• Quando il messaggio nomina una credenziale che ha la precedenza, come ANTHROPIC_API_KEY, un'impostazione apiKeyHelper o una chiave Console salvata da un /login precedente, rimuovetela nel modo che il messaggio dice, quindi eseguite /login
• Quando il messaggio dice che questa sessione remota si autentica attraverso la macchina che l'ha lanciata, accedete a claude.ai su quella macchina, quindi riconnettete la sessione
• Quando il messaggio dice che la credenziale è iniettata dall'ambiente host della sessione, non potete cambiarla in quella sessione; avviate una sessione che è connessa a claude.ai
• Vedete Disponibilità per gli altri requisiti che gli artifact hanno, come piano, provider di modello e politica dell'organizzazione

La politica dell'amministratore richiede un accesso al gateway Cloud

Un impostazione gestita di un amministratore su questa macchina ha impostato forceLoginMethod a "gateway" o ha impostato forceLoginGatewayUrl. A meno che non selezioniate un provider cloud attraverso una variabile come CLAUDE_CODE_USE_BEDROCK, Claude Code accetta quindi solo l'accesso gateway delle app Claude. Vedete uno di due messaggi:

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

Le richieste di modello falliscono con questo messaggio quando la sessione non ha alcun accesso al gateway, ad esempio perché non avete eseguito /login da quando la politica ha raggiunto la macchina.

Se avete anche una credenziale ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN o apiKeyHelper configurata e le impostazioni gestite impostano forceLoginMethod, Claude Code esce all'avvio invece con un messaggio che inizia:

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.

Cosa fare:

• Eseguite /login e completate l'accesso sulla schermata Cloud gateway
• Per il messaggio di avvio, rimuovete l'impostazione ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN o apiKeyHelper che avete configurato, quindi avviate claude ed eseguite /login
• Se ritenete che la macchina non dovrebbe richiedere il gateway, chiedete all'amministratore che la gestisce di rimuovere forceLoginMethod e forceLoginGatewayUrl dalle sue impostazioni gestite

Su v2.1.265, una regressione ha anche mostrato il primo messaggio in alcune configurazioni di gateway LLM e proxy che si autenticano con una chiave API, apiKeyHelper o intestazioni personalizzate, anche senza alcun requisito di amministratore sulla macchina. Aggiornate alla v2.1.266 o successiva. Non è necessario modificare la Vostra configurazione.

Prima della v2.1.261, su macchine che impostano forceLoginMethod a "gateway", Claude Code utilizzava un login salvato rimasto invece di fallire le richieste di modello, e segnalava una credenziale d'ambiente configurata con This machine's managed settings require a first-party login invece del messaggio di avvio. Prima della v2.1.265, una macchina le cui impostazioni gestite impostano solo forceLoginGatewayUrl non richiedeva l'accesso al gateway, e Claude Code utilizzava una credenziale rimasta lì.

Il Vostro account è in sospeso

L'account Claude dietro il Vostro login è stato sospeso. Claude Code mostra il primo messaggio quando tenta di rinnovare il Vostro login salvato e apprende della sospensione, e il secondo quando un accesso che completate nel browser lo 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

L'accesso di nuovo con lo stesso account non cancella il messaggio, perché la sospensione è sull'account piuttosto che sul login. In modalità non interattiva (-p) e Agent SDK, il codice di errore strutturato è account_on_hold. Prima della v2.1.235, Claude Code segnalava un account sospeso come Login scaduto · Please run /login, i cui passaggi di recupero non possono cancellare una sospensione.

Cosa fare:

• Aprite il link nel messaggio per visualizzare i dettagli della sospensione o presentare ricorso
• Se avete un altro account Claude o una chiave API che non è interessata dalla sospensione, potete continuare a lavorare mentre la sospensione viene risolta: eseguite /login con quell'account, oppure impostate la chiave con ANTHROPIC_API_KEY

Login del profilo Anthropic scaduto

Claude Code si sta autenticando attraverso un profilo di credenziale Anthropic la cui credenziale di login salvata è scaduta, e il profilo non contiene alcuna credenziale di aggiornamento che Claude Code possa utilizzare per rinnovarla. Claude Code ferma 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 appare solo quando la credenziale attiva proviene da un profilo di credenziale Anthropic, uno che selezionate con la variabile d'ambiente ANTHROPIC_PROFILE, che Claude Code scopre come il profilo attivo nella Vostra directory di configurazione Anthropic, o che Claude Code ha scritto quando vi siete acceduti senza una chiave API. Le sessioni che si autenticano con l'opzione claude.ai di /login, una chiave API, un token bearer come ANTHROPIC_AUTH_TOKEN o un provider di terze parti non vedono mai questo messaggio.

Su una macchina che offre l'accesso senza chiave, eseguite /login, scegliete l'account Anthropic Console e accedete di nuovo per rinnovare un profilo che l'accesso Console senza chiave o il CLI della Claude Platform ant auth login ha scritto. Claude Code sostituisce la credenziale scaduta in quel profilo. Per un profilo di federazione o uno che un altro strumento ha creato, /login non rinnova la credenziale. Quale forma vedete dipende dal fatto che abbiate selezionato il profilo o Claude Code l'abbia scoperto:

• Quando impostate ANTHROPIC_PROFILE esplicitamente, il messaggio termina con Re-authenticate your Anthropic profile.
• Quando Claude Code ha scoperto il profilo dalla Vostra directory di configurazione, il messaggio offre /login, perché Claude Code dà la precedenza a un /login funzionante rispetto al profilo scoperto e quindi si autentica con il Vostro account claude.ai o Console invece. Prima della v2.1.234, Claude Code mostrava il modulo Re-authenticate your Anthropic profile anche in questo caso.

Cosa fare:

• Accedete di nuovo al profilo, quindi riprovate: su una macchina che offre l'accesso senza chiave, eseguite /login e scegliete l'account Anthropic Console per un profilo che l'accesso Console senza chiave o il CLI della Claude Platform ant auth login ha scritto; per altri profili, utilizzate lo strumento che li ha creati
• Se un amministratore ha fornito la credenziale del profilo, chiedetegli di emetterne una nuova
• Eseguite /status per confermare la fonte di credenziale attiva e il nome del profilo
• Per smettere di utilizzare il profilo, annullate l'impostazione di ANTHROPIC_PROFILE se l'avete impostato, quindi autenticate in un altro modo, come /login o ANTHROPIC_API_KEY

Requisito di ambito OAuth

Il token memorizzato precede un ambito di autorizzazione che una funzione più recente necessita:

OAuth token does not meet scope requirement: user:profile

Cosa fare:

• Eseguite /login per ottenere un nuovo token con gli ambiti attuali. Non è necessario disconnettervi prima.

claude.ai ha rifiutato il token della sessione

Una richiesta connettore claude.ai è fallita perché claude.ai ha rifiutato il token dal Vostro login Claude Code. Il token rifiutato è il Vostro login, non l'autorizzazione del connettore in claude.ai, quindi autorizzare di nuovo il connettore non lo risolve. In /mcp, il connettore mostra come session token rejected e la sua vista dettagliata legge:

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

Cosa fare:

• Eseguite /login per accedere di nuovo
• Riconnettete il connettore da /mcp, oppure eseguite /mcp reconnect <server>. Riconnettere 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; il modulo /mcp reconnect <server> digitato segnala una riconnessione riuscita anche se il token è ancora rifiutato.

Prima della v2.1.222, Claude Code contrassegnava il connettore come necessitante di autenticazione invece, che vi indicava il flusso di autorizzazione del connettore anche se completarlo non risolveva lo stato.

MCP server ha bisogno che vi accediate di nuovo

Un server MCP remoto ha rifiutato la credenziale su una chiamata di strumento a metà sessione, di solito perché un accesso o un token è scaduto o perché il token manca di un'autorizzazione che lo strumento necessita. La chiamata di strumento fallisce, e /mcp contrassegna il server come necessitante di autenticazione.

Per un server a cui vi accedete 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)

Eseguite /mcp, selezionate il server e accedete di nuovo dal suo menu.

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

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)

Controllate che l'helper restituisca una credenziale che il server accetta, quindi riconnettete da /mcp, che riesegue 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)

Aggiornate il valore dell'intestazione dove il server è configurato, quindi riconnettete 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 di strumento con HTTP 403 insufficient_scope per chiedere di autorizzare un ambito, a volte uno che il Vostro token già elenca. Il messaggio nomina quell'ambito:

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

Eseguite /mcp, selezionate il server e autenticate di nuovo dal suo menu.

Quando la configurazione del server non imposta né oauth.scopes né authServerMetadataUrl, Claude Code richiede l'ambito che il server ha nominato. Con una delle due impostazioni, Claude Code richiede gli ambiti di quell'impostazione invece. Se avete fissato oauth.scopes, aggiungete l'ambito mancante a quell'elenco prima di autenticare 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 ha rifiutato di avviare un accesso OAuth per un server MCP remoto perché l'URL url configurato del server non viene analizzato come un URL. A meno che Claude Code non abbia un problema di configurazione più specifico da segnalare per il server, l'esecuzione di claude mcp login <name> nella Vostra 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:

• Impostate la voce url all'endpoint reale del server dove il server è configurato, o impostate la variabile d'ambiente che il suo riferimento ${VAR} nomina, quindi eseguite di nuovo l'accesso.

Mancata corrispondenza dell'emittente nella risposta di autorizzazione

Durante un accesso MCP OAuth, il server di autorizzazione ha reindirizzato di nuovo a Claude Code con un parametro iss che non nomina l'emittente che Claude Code si aspettava dai metadati OAuth del server. Un emittente sbagliato a questo passaggio è come appare un attacco di mix-up del server di autorizzazione, quindi Claude Code fallisce l'accesso invece di scambiare il codice di autorizzazione. Claude Code mostra l'errore nel menu del server /mcp dopo l'accesso del browser:

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

expected è l'emittente dai metadati OAuth del server, e received è il valore iss che il reindirizzamento ha trasportato. Un accesso il cui reindirizzamento non trasporta alcun parametro iss passa il controllo, a meno che i metadati del server non impostino authorization_response_iss_parameter_supported, nel qual caso Claude Code fallisce l'accesso.

Cosa fare:

• Riprovate l'accesso da /mcp
• Se l'errore si ripete, segnalarlo all'operatore del server. La correzione è lato server: il server di autorizzazione deve restituire lo stesso emittente nel parametro iss che pubblicizza nei suoi metadati
• Per connettervi mentre il server viene corretto, avviate 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 preferite la correzione lato server

Prima della v2.1.232, Claude Code utilizzava il runtime v2 solo in un rollout graduale o quando impostavate MCP_SDK_GENERATION=v2.

Rifiuto di inviare credenziali a un endpoint token non HTTPS

Sul runtime v2, Claude Code invia una richiesta di token MCP OAuth solo a un endpoint token servito su HTTPS o su localhost, 127.0.0.1 o ::1. Questo messaggio significa che l'endpoint token del server non è nessuno dei due, quindi Claude Code si è fermato prima di inviare la richiesta. Questo accade dopo l'accesso del browser, quindi il passaggio del browser ha successo per primo, 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 che ha rifiutato. Nel log di debug, segue Error during auth completion: per un accesso o Token refresh failed: per un aggiornamento. Nella Vostra shell, claude mcp login <name> lo stampa dopo Couldn't complete authentication for "<name>":, e in una sessione, /mcp lo mostra sotto il 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 tratta un URL del server che ha una stringa di query o un segmento di percorso lungo e casuale come possibilmente segreto. Per un tale server, redige gli errori di accesso che l'SDK MCP solleva prima di mostrarli o registrarli. Questo errore legge quindi come un nome breve che può cambiare tra i rilasci, come io, seguito da from the MCP SDK for e l'URL del server redatto. Gli altri errori dall'SDK MCP assumono la stessa forma lì. Il messaggio redatto può essere questo errore solo quando l'endpoint token del server è http:// semplice a un indirizzo diverso da localhost, 127.0.0.1 o ::1.

Cosa fare:

• Servite quell'endpoint token su HTTPS, ad esempio mettendo il server dietro un proxy inverso o un tunnel che termina TLS e configurando il server per pubblicizzare l'indirizzo https://
• Per connettervi senza modificare il server, avviate Claude Code con MCP_SDK_GENERATION=v1, il cui runtime non applica questa regola e invia la richiesta di token su HTTP semplice. Quella scelta dura fino a quando non uscite e si applica a ogni server. Il runtime v1 salta anche il controllo dell'emittente, quindi preferite servire l'endpoint su HTTPS

Credenziali AWS scadute o non valide

Il Vostro token di sessione AWS è scaduto o è stato rifiutato. Questo messaggio appare su un 401 da Claude Platform su AWS o dall'endpoint Mantle, che è come quei provider segnalano un token di sicurezza scaduto.

Il suggerimento di azione nel mezzo varia a seconda della Vostra configurazione. La parte stabile è il AWS credentials expired or invalid iniziale:

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 appariva solo quando awsAuthRefresh era configurato.

Cosa fare:

• Se il suggerimento dice che le credenziali sono gestite da questo ambiente, l'app che ha lanciato Claude Code possiede la credenziale e gli altri passaggi qui non si applicano: riprovate, o contattate il Vostro amministratore
• Se awsAuthRefresh è impostato, eseguite il comando nominato nel messaggio, come aws sso login --profile myprofile, in un altro terminale e completate l'accesso del browser, quindi riprovate. Altrimenti aggiornate la credenziale AWS che utilizzate voi stessi: il Vostro accesso SSO, le chiavi di accesso, la chiave API o il token proxy
• Con awsAuthRefresh impostato in una sessione interattiva, potete invece eseguire /login, scegliere 3rd-party platform, quindi selezionare Claude Platform on AWS · refresh credentials sotto Using 3rd-party platforms per eseguire lo stesso comando senza riavviare Claude Code. Vedete Configurare le credenziali AWS
• Se l'errore si ripete dopo che il comando di aggiornamento ha avuto successo, confermate che l'identità è valida al di fuori di Claude Code con aws sts get-caller-identity nella stessa shell e profilo

Autenticazione AWS non riuscita

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

Amazon Bedrock segnala un token di sicurezza scaduto come un 403, ma un 403 è anche come segnala un rifiuto di autorizzazione, come un AccessDeniedException da un'autorizzazione IAM mancante. Claude Code non può dire quale causa avete colpito.

Un 401 da Amazon Bedrock atterra anche qui piuttosto che sotto Credenziali AWS scadute o non valide, perché Amazon Bedrock non segnala un token scaduto come un 401. Un 401 da quell'endpoint di solito proviene da qualcos'altro nel percorso della richiesta, come un proxy aziendale.

Un aggiornamento delle credenziali corregge un token scaduto e non può correggere le altre cause, quindi il messaggio offre entrambi:

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 nel mezzo varia a seconda della Vostra configurazione. La parte stabile è il AWS authentication failed iniziale.

Quando il 403 è la risposta di Amazon Bedrock che non avete accesso al modello con l'ID modello specificato, il suggerimento invece vi dice di abilitare il modello per il Vostro account e la Vostra regione nella console Amazon Bedrock.

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

Cosa fare:

• Se il suggerimento dice che le credenziali sono gestite da questo ambiente, l'app che ha lanciato Claude Code possiede la credenziale e gli altri passaggi qui non si applicano: riprovate, o contattate il Vostro amministratore
• Aggiornate le Vostre credenziali AWS nel caso in cui una credenziale scaduta sia la causa: eseguite il comando awsAuthRefresh nominato nel messaggio quando uno è impostato, o aggiornate il Vostro accesso SSO, le chiavi di accesso, la chiave API o il token proxy voi stessi
• Se le Vostre credenziali sono attuali, confermate che le autorizzazioni IAM in Configurazione IAM siano allegate all'identità che state utilizzando e che il modello selezionato sia abilitato per il Vostro account e la Vostra regione
• Eseguite aws sts get-caller-identity per confermare quale identità le Vostre richieste utilizzano

Credenziali Google Cloud scadute o non valide

Le Vostre credenziali Google Cloud per Agent Platform di Google Cloud sono scadute o sono state rifiutate: la richiesta ha restituito un 401, che è come Agent Platform segnala la scadenza delle credenziali.

Il suggerimento di azione nel mezzo varia a seconda della Vostra configurazione. La parte stabile è il Google Cloud credentials expired or invalid iniziale:

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 lanciato Claude Code possiede la credenziale e gli altri passaggi qui non si applicano: riprovate, o contattate il Vostro amministratore
• Se vi autenticate con le credenziali predefinite dell'applicazione, eseguite il comando gcpAuthRefresh nominato nel messaggio, o gcloud auth application-default login, e completate l'accesso, quindi riprovate
• Se instradare attraverso un gateway LLM con CLAUDE_CODE_SKIP_VERTEX_AUTH impostato, aggiornate il token del gateway in ANTHROPIC_AUTH_TOKEN o ANTHROPIC_CUSTOM_HEADERS, quindi riprovate
• Se vi autenticate con un file di chiave dell'account di servizio, confermate che GOOGLE_APPLICATION_CREDENTIALS punti a una chiave valida. Vedete Configurare le credenziali GCP
• Se l'errore si ripete dopo un aggiornamento, confermate che l'identità funziona 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 il messaggio generico Please run /login o Failed to authenticate invece, che non può aggiornare le credenziali Google Cloud.

Autenticazione Google Cloud non riuscita

Agent Platform di Google Cloud ha restituito un 403, che utilizza per i rifiuti di autorizzazione piuttosto che per le credenziali scadute. Di solito l'identità con cui vi autenticate manca di un'autorizzazione IAM, oppure il modello non è abilitato per il Vostro progetto.

Il suggerimento di azione nel mezzo varia a seconda della Vostra configurazione. La parte stabile è il Google Cloud authentication failed iniziale:

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 dice che le credenziali sono gestite da questo ambiente, l'app che ha lanciato Claude Code possiede la credenziale e gli altri passaggi qui non si applicano: riprovate, o contattate il Vostro amministratore
• Confermate che i ruoli in Configurazione IAM siano concessi all'identità con cui vi autenticate
• Confermate che il modello sia abilitato per il Vostro progetto. Vedete Richiedere l'accesso al modello

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

Autenticazione Microsoft Foundry non riuscita

Microsoft Foundry ha restituito un 401 o 403: la credenziale Azure sulla richiesta è stata rifiutata, oppure l'identità dietro di essa non ha accesso alla risorsa Foundry. /login non può coniare credenziali Azure. Il suggerimento di azione nel mezzo varia a seconda della Vostra configurazione. La parte stabile è il Microsoft Foundry authentication failed iniziale:

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 dice che le credenziali sono gestite da questo ambiente, l'app che ha lanciato Claude Code possiede la credenziale e gli altri passaggi qui non si applicano: riprovate, o contattate il Vostro amministratore
• Aggiornate la credenziale che avete configurato in Configurare le credenziali Azure: ruotate ANTHROPIC_FOUNDRY_API_KEY, coniate un ANTHROPIC_FOUNDRY_AUTH_TOKEN fresco, o eseguite az login in modo che la catena di credenziali Microsoft Entra predefinita possa accedere di nuovo
• Se la credenziale è attuale, confermate che l'identità ha accesso alla risorsa Foundry. Vedete Configurazione RBAC di Azure

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

Impossibile caricare le credenziali AWS o Google Cloud

Claude Code non ha potuto ottenere credenziali utilizzabili dalla catena del provider di credenziali AWS o dalle Vostre credenziali predefinite dell'applicazione Google sulla macchina su cui viene eseguito, quindi nessuna richiesta ha raggiunto il Vostro provider cloud. Claude Code cancella le Vostre credenziali memorizzate nella cache e ritenta due volte prima di mostrare questo messaggio. Il dettaglio dopo il · nomina la causa specifica, come una sessione SSO scaduta, credenziali predefinite mancanti segnalate come Could not load the default credentials, o 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 in 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:

• Eseguite il comando di accesso del Vostro provider, come aws sso login --profile myprofile o gcloud auth application-default login, quindi riprovate. Credenziali Bedrock, Agent Platform o Foundry non si caricano mostra come confermare le credenziali al di fuori di Claude Code
• Se il dettaglio legge AWS default-chain credential resolve timed out, la catena si è bloccata piuttosto che fallire, quindi seguite Timeout della risoluzione delle credenziali della catena predefinita AWS invece

Timeout della risoluzione delle credenziali della catena predefinita AWS

La catena del provider di credenziali predefinite AWS non ha prodotto credenziali entro 60 secondi, quindi Claude Code ha fermato la risoluzione e ha fallito la richiesta. Questo timeout è una causa di Impossibile caricare le credenziali AWS o Google Cloud. L'errore è la risoluzione delle credenziali locali: la richiesta non ha mai raggiunto Amazon Bedrock, Claude Platform su AWS o l'endpoint Mantle. Claude Code cancella la Vostra cache delle credenziali e ritenta prima che questo errore emerga, quindi al momento in cui lo vedete la catena si è bloccata su 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 Vostro profilo AWS che attende un input che non può ricevere, e un contenitore o una VM il cui servizio di metadati dell'istanza (IMDS) non risponde mai al probe della catena.

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

Cosa fare:

• Eseguite aws sts get-caller-identity nella stessa shell con lo stesso AWS_PROFILE. Se si blocca anche, correggete il profilo; un comando credential_process che richiede in modo interattivo è una causa comune.
• Completate il passaggio di accesso prima di avviare Claude Code, ad esempio aws sso login --profile myprofile, in modo che la catena si risolva dalla cache SSO locale invece di attendere un flusso del browser
• Se la Vostra catena esegue un accesso interattivo che legittimamente ha bisogno di più di 60 secondi, come SSO con MFA attraverso un wrapper come aws-vault, aumentate 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 procedura guidata di configurazione di Bedrock, come la ricerca delle credenziali o il controllo dell'identità, non è stata completata entro il limite di 60 secondi. La procedura guidata smette di attendere e fallisce 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 Vostro limite: 60 secondi per impostazione predefinita, o il valore che impostate 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 di credenziali ancora in attesa di input che non potete vedere. Aumentate il limite solo quando l'helper legittimamente ha bisogno di più tempo.

Una singola richiesta bloccata ad AWS può anche fallire sul suo timeout per richiesta, che mostra un messaggio più breve sullo stesso passaggio:

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

Quando gli stessi timeout si verificano sul passaggio di pin del modello, la procedura guidata contrassegna un modello come unreachable invece di mostrare uno dei due messaggi.

Cosa fare:

• Eseguite aws sts get-caller-identity nella stessa shell. Se si blocca anche, il blocco è al di fuori di Claude Code, nella Vostra rete, nel Vostro proxy o nell'helper di credenziali nel Vostro profilo AWS; correggete prima quello.
• Completate qualsiasi accesso interattivo prima di aprire la procedura guidata, ad esempio aws sso login --profile myprofile
• Se un helper di credenziali nel Vostro profilo AWS legittimamente ha bisogno di più di 60 secondi per richiedervi, aumentate il limite in millisecondi con CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS

Sessione del gateway cloud scaduta

Vi siete acceduti attraverso un gateway delle app Claude, e la sessione del gateway salvata su questa macchina è scaduta e non ha potuto essere rinnovata, oppure il gateway non la accetta più, ad esempio dopo che il JWT secret del gateway è stato sostituito. Se vedete questa riga quando avviate claude in modo interattivo, la sessione si è aperta disconnessa dal gateway:

Cloud gateway session expired — run /login to reconnect.

La stessa riga può apparire a metà sessione quando la credenziale del gateway scade e Claude Code non può rinnovarla.

In un'esecuzione non interattiva, una sessione in background o altra sessione incustodita, o un sottocomando claude diverso da claude auth, Claude Code esce con questo messaggio invece 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:

• Eseguite /login nella sessione e completate l'accesso del browser
• Per un lancio non interattivo, avviate claude nello stesso ambiente, eseguite /login, quindi rieseguite il Vostro comando

Sign-in scaduto mentre vi aspettava di continuare

Durante un accesso al gateway delle app Claude, il gateway ha nominato l'account che ha effettuato l'accesso, e Claude Code vi ha chiesto di confermarlo prima di salvare la credenziale. Avete lasciato la conferma aperta oltre la scadenza dell'accesso stesso, e il gateway non ha emesso alcun token di aggiornamento che potesse rinnovarlo, quindi Claude Code non ha memorizzato nulla quando avete continuato:

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

Cosa fare:

• Eseguite /login di nuovo e confermate l'account prima che l'accesso scada

Il gateway ha rifiutato la richiesta

Siete connessi attraverso un gateway delle app Claude, e una richiesta ha restituito un 403: il gateway, o l'upstream dietro di esso, l'ha rifiutata. L'accesso di nuovo non cambia un rifiuto, quindi il messaggio punta al Vostro amministratore del gateway:

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

Cosa fare:

• Chiedete al Vostro amministratore del gateway di cercare la richiesta. La coda API Error: trasporta il rifiuto che il gateway ha restituito
• Per gli amministratori: una regola di controllo dell'accesso sul gateway restituisce un 403 che il log di audit registra con il suo motivo, e un rifiuto di autorizzazione dell'upstream passa attraverso per Messaggi di errore dell'upstream

Prima della v2.1.273, un 403 su una sessione del gateway mostrava il messaggio generico Please run /login o Failed to authenticate invece, e l'accesso di nuovo non cancellava 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 la routine per la modifica, o avvia una sessione cloud. Seleziona l'icona cloud che mostra il nome del tuo ambiente, come Default, per aprire il selettore. Passa il mouse sopra il tuo ambiente e fai clic sull'icona delle impostazioni.
• Nella finestra di dialogo Update 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 e effort 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 di 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 ordinario errore di 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 ritentativo 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 Run /model to see available models. Invece. 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 limite di velocità 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 limite di velocità 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 autentica 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 elenco di autorizzazione 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 un agente, abilità o nome di comando significa che la restrizione si è applicata al modello richiesto di quel subagente: il subagente 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 subagenti 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 subagente, abilità o 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 elenco di autorizzazione availableModels gestito 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 il prompt 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.

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 thinking 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

L'effort non è disponibile con il thinking disattivato

Hai disattivato il thinking esteso e hai eseguito a un livello di effort 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 effort a high o inferiore.
• Attiva il thinking di nuovo, 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 effort che hai impostato, quindi Opus 5 rifiutava ogni richiesta superiore a high con il thinking disattivato. Claude Code ora invia effort high ai modelli che sa rifiutano la combinazione, come Opus 5.

Il budget di thinking supera il limite di output

Il budget di thinking 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 thinking
• Vedi Extended thinking per come il budget interagisce con la lunghezza dell'output

Mancata corrispondenza di blocco tool use o thinking

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 dello strumento, 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 thinking 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 thinking:

[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 di strumento 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 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 con <model>'s safeguards flagged this session invece. 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 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 da riga di comando

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

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

Questo messaggio richiede Claude Code v2.1.198 o successivo. Avete combinato --bg con -p o --print nella stessa invocazione di claude. --bg avvia una sessione in background a cui vi collegherete successivamente con claude agents, mentre --print esegue in modo non interattivo e non avvia mai la sessione interattiva a cui claude agents si collega. Prima della v2.1.198 questa combinazione creava silenziosamente un lavoro in background che non poteva mai essere collegato.

--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:

• Eliminate -p o --print. --bg accetta il prompt come argomento posizionale, quindi claude --bg "<task>" è il comando completo. Vedete Dispatch new agents from your shell.
• Per eseguire il prompt in modo non interattivo e stampare il risultato invece di creare una sessione in background, eliminate --bg ed eseguite claude -p "<task>"

Configurazione `--agents` non valida

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

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

Quello che segue la prima riga dipende da come il valore ha fallito. Claude Code esegue questi controlli in ordine e si ferma al primo che fallisce. Se il vostro valore ha due tipi di problema, vedete il secondo solo dopo aver corretto il primo:

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

Quando ci sono più di 20 righe di problema, Claude Code stampa le prime 20 e sostituisce il resto 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 di file ha i suoi rifiuti, stampati al posto di questo messaggio, inclusi 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. Passate le definizioni come JSON inline, oppure aggiungete -p per leggerle da un file.
• Error: --agents file not found: <path>: nessun file esiste in quel percorso. Un valore che non inizia con { e non è JSON valido viene letto come percorso, quindi JSON inline che la vostra shell ha danneggiato può fallire in questo modo. Controllate il percorso o le virgolette e eseguite di nuovo il comando.

Cosa fare:

• Correggete ogni problema che il messaggio elenca, quindi eseguite di nuovo il comando. Vedete i campi che un subagente definito da CLI accetta.

Le sessioni cloud non possono essere create da una sessione `--restricted`

Quando avviate una sessione con --restricted, Claude Code rifiuta di creare sessioni cloud da essa, perché la nuova sessione verrebbe eseguita al di fuori del processo ristretto e non farebbe rispettare la modalità ristretta. Claude Code rifiuta dal client, prima di contattare il server, quindi nessuna sessione cloud viene creata:

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

Cosa fare:

• Eseguite l'attività localmente nella sessione ristretta
• Se controllate come è stata avviata la sessione, avviate una nuova sessione claude senza --restricted e create 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 politica della vostra organizzazione

La politica allow_remote_sessions della vostra organizzazione è disattivata, quindi le sessioni cloud e i comandi che le utilizzano non sono disponibili:

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

Il messaggio appare quando create una sessione cloud dal terminale e quando inviate un comando che ha bisogno di sessioni cloud, come /teleport, /remote-env o /web-setup. Prima della v2.1.268, l'invio di uno di questi comandi restituiva Unknown command invece.

Questa è una politica organizzativa lato server, quindi non può essere ignorata dalle impostazioni locali, dalle variabili di ambiente o dai flag CLI.

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

Cosa fare:

• Chiedete a un Owner della vostra 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 ha potuto verificare la politica, controllate la vostra connessione di rete, quindi riavviate Claude Code e riprovate

Il valore `--json-schema` non è uno schema JSON valido

Lo schema che avete passato a --json-schema in modalità non interattiva ha fallito la compilazione dello schema JSON, quindi claude esce con codice 1 invece di eseguire il prompt. Prima della v2.1.205, uno schema non valido produceva output non strutturato senza errore, e qualsiasi schema che utilizzava la parola chiave format era 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 il secondo due punti è la diagnostica del validatore e nomina la parola chiave o la posizione che ha fallito. Gli schemi che utilizzano la parola chiave format, come "format": "email", sono validi: Claude Code accetta format come annotazione e non la 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 JSON valido che non è un oggetto con Error: --json-schema must be a JSON object.

Cosa fare:

• Correggete la parte dello schema che la diagnostica nomina, quindi rieseguite il comando
• Vedete Get structured output per uno schema funzionante e un comando

Il file di impostazioni supera il limite di 2MiB

Il file che avete passato a --settings è più grande di 2 MiB, quindi claude esce con codice 1 all'avvio invece di caricarlo. Prima della v2.1.214, Claude Code leggeva il file senza controllo delle dimensioni, e un file di più gigabyte o un file di dispositivo come /dev/zero faceva crescere la memoria senza limiti.

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

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

Cosa fare:

• Puntate --settings a un file JSON di impostazioni regolare sotto 2 MiB. Vedete Settings per il formato.

La directory corrente non esiste più

Avete avviato claude da una directory che è stata eliminata o spostata dopo che la vostra shell vi è entrata, ad esempio una worktree o una directory temporanea che un'altra shell ha rimosso. Claude Code non riesce a leggere la sua directory di lavoro, quindi esce con codice 1 prima di avviare la sessione, sia in modalità interattiva che non interattiva. Prima della v2.1.239, Claude Code si bloccava con il codice sorgente del bundle minificato e uno stack ENOENT ... uv_cwd grezzo su stderr 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 un cambio di permessi, il messaggio nomina il codice di errore invece: 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 vostra app terminale a quella cartella. Altri comandi che leggono quella cartella falliscono allo stesso modo: ls lì segnala Operation not permitted, anche con sudo.

Cosa fare:

• Cambiate a una directory che esiste, come la vostra home o la directory del progetto, quindi eseguite di nuovo claude
• Se la directory è stata ricreata nello stesso percorso, la vostra shell tiene ancora quella eliminata. Eseguite cd "$PWD" o lasciate e rientrate nella directory, quindi eseguite di nuovo claude
• Per EPERM su macOS, chiudete la vostra app terminale con Cmd+Q, apritela di nuovo, tornate a quella cartella ed eseguite claude. Se ls in quella cartella continua a fallire, aprite System Settings > Privacy & Security > Files and Folders, attivate la cartella per la vostra app terminale, quindi riaprire il terminale

La directory temporanea è stata rifiutata o non può essere creata

Su macOS e Linux, Claude Code crea una directory temporanea privata all'avvio, claude-<uid> sotto la directory temporanea di sistema o l'override CLAUDE_CODE_TMPDIR. Quando la directory non può essere creata, o una voce già in quel percorso fallisce i controlli di sicurezza, Claude Code stampa l'errore su stderr ed esce con codice 1 piuttosto che 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, liberate spazio su disco nel volume che contiene la directory temporanea
• Per le forme Refusing to use it, rimuovete la voce denominata stessa, non quello a cui un link punta, e avviate di nuovo Claude Code; per la forma owned by uid, solo un amministratore o quell'utente può rimuoverla
• Per is not readable, eseguite chmod 0700 sulla directory denominata, oppure rimuovetela e avviate di nuovo
• In uno qualsiasi di questi casi, impostate CLAUDE_CODE_TMPDIR a una directory che controllate e avviate di nuovo Claude Code, lasciando il percorso rifiutato da solo

La directory non ha potuto essere risolta a una posizione reale

Avete eseguito /add-dir per una sottodirectory della vostra directory di lavoro, e Claude Code non ha potuto risolvere la directory alla sua posizione reale.

Avete già accesso ai file a una sottodirectory della directory di lavoro, quindi /add-dir carica solo le sue skills, comandi e agenti. Prima di caricarli, Claude Code controlla che la posizione reale della directory, con qualsiasi symlink risolto, sia dentro la 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:

• Controllate che il percorso nomini una directory reale dentro la directory di lavoro, quindi eseguite di nuovo /add-dir
• Il messaggio non cambia l'accesso ai vostri file; riporta 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 era su un automount /net/<host>, dove Claude Code rifiuta di risolvere i percorsi per progettazione; la directory era fine e riprovare non poteva aiutare.

Workspace non attendibile all'avvio di Remote Control

Avete avviato la modalità server Remote Control con claude remote-control o il suo alias claude rc in una directory che non avete attendibile, e il comando non ha potuto chiedervi se fidarvi di essa. Ad esempio, l'input standard o l'output standard del comando non è un terminale perché uno di essi è reindirizzato o pipato. Il comando esce con codice 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 anche con Error: Workspace not trusted. appaiono anche in un terminale troppo piccolo per mostrare cosa attiva l'attendibilità della directory, o uno che non ha segnalato le sue dimensioni. Ingrandite la finestra o passate a una finestra terminale normale, quindi eseguite di nuovo claude rc.

Nella vostra home directory il messaggio è diverso, perché la finestra di dialogo di attendibilità dell'area di lavoro non salva mai l'attendibilità per la home directory, quindi accettarla lì non può soddisfare questo controllo. Prima della v2.1.214, la home directory mostrava il messaggio sopra, il cui consiglio non può avere successo lì.

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 rispondete n o premete Invio alla domanda Trust <directory>?, il comando stampa un messaggio Remote Control did not start che nomina la directory ed esce con codice 1. Eseguite di nuovo claude rc per rispondere y.

Cosa fare:

• Attendete la directory da un terminale prima: eseguite claude rc lì e rispondete y, oppure eseguite claude lì e accettate la finestra di dialogo di attendibilità dell'area di lavoro, quindi eseguite di nuovo il vostro comando originale
• Nella vostra home directory, cambiate a una directory di progetto e avviate Remote Control lì

Prima della v2.1.284, il comando non ha mai chiesto, nemmeno in un terminale.

Non trasportato alle sessioni che Remote Control avvia

Avete avviato Remote Control con un flag claude globale prima del verbo remote-control, uno che limiterebbe o configurerebbe le sessioni che Remote Control avvia, come --settings, --setting-sources, --permission-mode, --disallowed-tools o --mcp-config. Un flag posizionato prima del verbo non raggiunge mai quelle sessioni. Claude Code rifiuta di avviare invece, nominando 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 sono innocui da eliminare, come --verbose, --model o un --session-id o --plugin-dir iniettato da wrapper: li ignora e Remote Control si avvia.

Claude Code rifiuta anche di avviare per un flag globale che non riconosce ancora come innocuo, quindi un flag aggiunto in una versione più recente può apparire in questo messaggio fino a quando una versione successiva non lo contrassegna come innocuo.

Cosa fare:

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

Prima della v2.1.248, claude remote-control non accettava i suoi flag quando un flag globale veniva per primo, e il comando falliva con un errore di opzione sconosciuta.

claude import non è ancora disponibile in questa build

Avete eseguito claude import, e Claude Code ha trovato il flusso di importazione disattivato, quindi il comando esce con codice 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 attraverso un feature flag che recupera da Anthropic e memorizza nella cache su disco. Questo messaggio significa che il valore memorizzato nella cache è disattivato. La causa è di solito una delle seguenti:

• Non avete avviato una sessione dall'installazione, quindi Claude Code non ha ancora recuperato il flag. Il primo claude import può stampare questo anche quando la funzione è disponibile per voi.
• Utilizzate Claude Code attraverso Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, o Claude Platform su AWS, o attraverso un gateway di app Claude. Claude Code non recupera i feature flag in queste sessioni, quindi claude import rimane non disponibile.
• Avete impostato DISABLE_TELEMETRY, DO_NOT_TRACK, DISABLE_GROWTHBOOK o CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, che disattivano il recupero dei feature flag, quindi claude import rimane non disponibile.

Cosa fare:

• Su un'installazione nuova, avviate claude, aspettate che la sessione si carichi, uscite ed eseguite di nuovo claude import
• Dove il recupero dei feature flag rimane disattivato, impostate la configurazione voi stessi: aggiungete server MCP con claude mcp add, e create i file CLAUDE.md, skills e comandi e subagenti che volete trasportare. Il messaggio nomina anche ~/.claude/settings.json. Della configurazione che claude import trasporta, quel file contiene solo la modalità di permesso; Claude Code non legge i server MCP da esso.

Non è stato possibile leggere la configurazione di Claude Code

Avete eseguito claude import mentre Claude Code non poteva analizzare ~/.claude.json, il file dove memorizza il vostro login e lo stato per progetto. Il sottocomando legge quel file per controllare la disponibilità ma non mostra la finestra di dialogo di recupero che la sessione interattiva mostra, quindi esce con codice 1. Prima della v2.1.222, claude import con un file di configurazione illeggibile avviava una sessione interattiva, la cui finestra di dialogo di recupero gestiva il file.

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

Cosa fare:

• Eseguite claude senza argomenti. Claude Code rileva il file non valido e offre di ripristinarlo. Quindi eseguite di nuovo claude import.
• Per mantenere le modifiche manuali che avete fatto, correggete la sintassi JSON in ~/.claude.json in un editor invece, quindi rieseguite claude import

Non è stato possibile importare un server da Claude Desktop

Claude Code non ha potuto aggiungere uno dei server che avete selezionato in claude mcp add-from-claude-desktop. Il comando importa comunque gli altri server selezionati e stampa una riga per server che non ha potuto aggiungere. Prima della v2.1.205, il primo server che falliva fermava 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 caratteri nei nomi dei server, come spazi e punti, che claude mcp limita a lettere, numeri, trattini e sottolineature. Altri motivi includono una configurazione del server che fallisce la convalida e un server bloccato dalla politica MCP della vostra organizzazione.

Cosa fare:

• Rinominate il server in claude_desktop_config.json per utilizzare solo lettere, numeri, trattini e sottolineature, quindi eseguite di nuovo claude mcp add-from-claude-desktop
• Aggiungete quel server direttamente con claude mcp add o claude mcp add-json con un nome valido. Vedete Import MCP servers from Claude Desktop.

Non è possibile aggiungere un server MCP all'ambito gestito

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

Cannot add MCP server to scope: managed

Cosa fare:

• Aggiungete il server a un ambito in cui potete scrivere: local, user o project. Senza --scope, il comando utilizza local. Vedete MCP installation scopes
• Per fornire il server a ogni utente della vostra organizzazione, aggiungetelo a managedMcpServers nelle impostazioni gestite che distribuite

Non è possibile leggere .mcp.json

Un comando che legge il .mcp.json del progetto, come claude mcp add o claude mcp add-json con --scope project, o claude mcp remove, ha trovato che il file nella vostra directory corrente non è un file regolare o è più grande di 2 MiB, quindi esce 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, un FIFO in .mcp.json lasciava il comando in attesa per sempre senza output, e un symlink a un file di dispositivo come /dev/zero faceva crescere la memoria fino a quando il processo non veniva ucciso.

Cosa fare:

• Controllate cosa si trova in .mcp.json nella vostra directory corrente. Sostituitelo con un file JSON ordinario nel formato project-scope, oppure eliminatelo, quindi eseguite di nuovo il comando.

Il server MCP non è stato salvato o rimosso

Avete eseguito claude mcp add, claude mcp add-json o claude mcp remove per un server nell'ambito user o local scope. Entrambi gli ambiti sono memorizzati in ~/.claude.json, e la modifica non è in quel file quando Claude Code lo legge di nuovo dopo la scrittura. Il comando esce 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 legge was not removed from e termina con then remove the server again. Per un server local-scope, 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 segnalano il successo anche quando la modifica non raggiungeva il file.

Cosa fare:

• Rendete il file che il messaggio nomina scrivibile, oppure eseguite il comando al di fuori della sandbox, quindi eseguite di nuovo lo stesso comando di aggiunta o rimozione.

Il server MCP potrebbe non essere stato salvato o rimosso

Avete eseguito claude mcp add, claude mcp add-json o claude mcp remove per un server nell'ambito user o local scope, e Claude Code non ha potuto leggere ~/.claude.json di nuovo per confermare la modifica. La modifica potrebbe essere o non essere su disco. Il testo tra parentesi è l'errore da 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 legge 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 segnalano il successo anche quando la modifica non poteva essere confermata.

Cosa fare:

• Eseguite claude mcp get <name> per controllare se la modifica è su disco. Per un server local-scope, eseguitelo 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, eseguite di nuovo lo stesso comando di aggiunta o rimozione.

Il server è ospitato da Anthropic e non supporta OAuth locale

Avete avviato un accesso per un server MCP il cui URL punta a un host di connettore ospitato da Anthropic che si autentica attraverso 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 rifiuta di avviare il suo flusso OAuth locale per questi host sia dal pannello /mcp che da claude mcp login, perché il loro accesso funziona solo attraverso 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:

• Rimuovete la vostra voce con claude mcp remove <name>, in modo che non possa nascondere il connettore claude.ai allo stesso URL
• Dopo averlo rimosso, collegate il servizio su claude.ai/customize/connectors, mentre siete connessi all'account che utilizzate in Claude Code. Una volta collegato, il connettore appare in Claude Code automaticamente se il vostro metodo di autenticazione attivo è un accesso di sottoscrizione a claude.ai

Il server ha rifiutato l'intestazione Authorization creata dal headersHelper configurato

Un server MCP il cui headersHelper fornisce l'intestazione Authorization ha risposto alla connessione con HTTP 401 o 403, quindi Claude Code segnala la connessione come fallita. Poiché l'helper fornisce l'intestazione Authorization, Claude Code non ricade 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 riesegue l'helper ad ogni tentativo di connessione, quindi un nuovo tentativo dopo un rifiuto transitorio, come una gara di rotazione del token, può avere successo con una credenziale nuova.

Cosa fare:

• Eseguite il comando headersHelper voi stessi nel modo in cui Claude Code lo esegue: dalla directory in cui Claude Code lo esegue, con le variabili di ambiente che Claude Code imposta per esso, e senza le variabili di credenziale che Claude Code rimuove per un server da un .mcp.json di progetto, un plugin o un file di agente di progetto. Controllate che stampi un valore Authorization che l'endpoint del server accetta
• Dopo aver corretto l'helper o la sua fonte di credenziale, selezionate il server in /mcp e scegliete Reconnect

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

Strumento di prompt di permesso MCP non trovato

Lo strumento che avete 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 di permesso, perché il suo server non si è mai connesso o perché nessun server connesso espone uno strumento con quel nome. Claude Code invia comunque il vostro prompt: l'esecuzione non interattiva esce con questo errore, e codice di uscita 1, alla prima chiamata dello strumento, quindi non produce alcuna risposta anche se la richiesta è stata fatta. Prima del primo prompt, Claude Code aspetta fino al timeout di connessione per server di 30 secondi impostato da MCP_TIMEOUT affinché quel server si connetta. Prima della v2.1.206, l'avvio non aspettava che il server finisse di connettersi, quindi un server che si avvia lentamente ma sano produceva questo errore anche.

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

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

Cosa fare:

• Controllate che il server si avvii e rimanga connesso: eseguite claude mcp list nella stessa directory e confermate che il server è elencato come connesso
• Confermate che il nome dello strumento corrisponda al nome mcp__<server>__<tool> che il server espone
• Se il server ha bisogno di più di 30 secondi per avviarsi, aumentate MCP_TIMEOUT

La porta di callback OAuth è già in uso

Quando vi accedete a un server MCP remoto con OAuth, Claude Code avvia un listener locale per ricevere il callback di accesso. Se la porta di cui quel listener ha bisogno è tenuta da un altro processo, l'accesso fallisce con questo messaggio. Questo accade principalmente con una porta di callback fissa impostata attraverso la variabile MCP_OAUTH_CALLBACK_PORT o --callback-port, poiché senza una 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 è netstat -ano | findstr :<port> invece.

Cosa fare:

• Eseguite il comando dal messaggio per trovare il processo che tiene la porta, e fermatelo o aspettate che finisca
• Se un altro programma ha bisogno di quella porta in modo permanente, registrate un URI di reindirizzamento diverso con il server e impostate la sua porta con MCP_OAUTH_CALLBACK_PORT o --callback-port, a seconda di quale utilizzate
• Quindi avviate di nuovo l'accesso, ad esempio selezionando il server in /mcp

Nessuna porta disponibile per il reindirizzamento OAuth

Quando vi accedete 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 legare una porta locale per esso. Qualcosa sulla macchina sta impedendo di ascoltare su 127.0.0.1, ad esempio software di sicurezza o una politica sandbox che nega i listener locali.

No available ports for OAuth redirect

Prima della v2.1.268, Claude Code non ricadeva su una porta assegnata dal sistema operativo, quindi il messaggio appariva anche quando solo le porte auto-scelte non potevano essere legate. Questo può accadere su host Windows dove Hyper-V riserva intervalli di porte che coprono le porte che Claude Code sceglie.

Cosa fare:

• Controllate se il software di sicurezza o una politica sandbox blocca i processi dall'ascolto su 127.0.0.1, e consentite a Claude Code di legare una porta locale
• Quindi avviate di nuovo l'accesso, ad esempio selezionando il server in /mcp

/security-review fallisce senza origin/HEAD

/security-review costruisce il suo contesto di revisione facendo il diff del vostro ramo rispetto a origin/HEAD, il ref locale che registra quale ramo è il predefinito sul vostro remote origin. Quando quel ref non esiste, i comandi git che raccolgono il diff falliscono e la revisione si ferma 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 git log o un diverso git diff invece. Git crea origin/HEAD solo quando il remote pubblicizza un ramo predefinito e il vostro refspec di fetch lo copre, cosa che un git clone completo di un remote con commit fa. Il ref manca in queste configurazioni:

• Un checkout single-branch o CI, che recupera un refspec troppo stretto
• Un remote il cui server-side HEAD punta a un ramo che nessuno ha spinto
• Un repository senza remote origin, o uno da cui non avete mai recuperato

Claude Code mostra lo stesso errore per qualsiasi skill che inietta contesto dinamico, e un comando iniettato fallito interrompe l'invocazione di quella skill. Due stringhe sibling si attivano prima che il comando venga eseguito:

• Shell command permission check failed for pattern "...": il controllo di permesso del comando non lo ha consentito. Permission checks on injected commands copre quali risultati interrompono in ogni 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 senza di esso. Installate Git per Windows o cambiate il frontmatter a shell: powershell. Vedete How injected commands run

Cosa fare:

• Create il ref nominando il ramo predefinito del vostro remote: git remote set-head origin <default-branch>. Questo funziona ogni volta che il ref di tracciamento locale origin/<default-branch> esiste. Se non esiste, come nei cloni single-branch, recuperate prima il ramo: eseguite git remote set-branches --add origin <branch>, quindi git fetch origin, quindi rieseguite il comando set-head. Rieseguite /security-review.
• Se preferite non nominare il ramo, eseguite git fetch origin e quindi git remote set-head origin --auto, che chiede al remote quale ramo è il suo predefinito. Fallisce con error: Cannot determine remote HEAD quando il remote non pubblicizza alcun ramo predefinito, perché è vuoto o il suo HEAD punta a un ramo che nessuno ha spinto; nominate il ramo esplicitamente invece. Fallisce con error: Not a valid ref quando il vostro clone non recupera quel ramo; allargare il refspec come sopra prima.
• Se il repository non ha un remote, aggiungete uno con git remote add origin <url> e recuperate prima di creare il ref. Se il remote è vuoto, spingete il vostro ramo prima con git push -u origin HEAD e nominate quel ramo nel comando set-head; origin/HEAD quindi punta al ramo che avete appena spinto, quindi /security-review vede un diff vuoto fino a quando il ramo non diverge da esso.

L'input deve essere fornito quando si utilizza `--print`

claude nudo ha bisogno che stdout sia un terminale per avviare l'interfaccia utente interattiva. Quando stdout è reindirizzato, o la console non è un vero terminale, come PowerShell ISE e alcuni riquadri di output IDE, claude esegue in modo non interattivo invece. Questa è la stessa modalità di claude -p, che richiede un prompt, quindi il messaggio nomina --print anche se non avete passato il flag. Passare -p/--print senza prompt e nulla pipato 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, eseguite claude in un vero terminale: Windows Terminal o la console PowerShell piuttosto che ISE, e il terminale integrato del vostro IDE piuttosto che un riquadro di output
• Per l'uso una tantum, passate il prompt: claude -p "your question", oppure pipate con echo "your question" | claude -p

L'input conteneva solo spazi bianchi

In modalità non interattiva, Claude Code rifiuta un prompt composto interamente da spazi, tabulazioni o newline invece di inviarlo, perché l'API rifiuta i messaggi senza testo visibile. Quale messaggio vedete dipende da dove è venuto il prompt vuoto:

• Argomento prompt o stdin pipato per claude -p: claude esce 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 rimane 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 il messaggio solo spazi bianchi all'API, che rifiutava la richiesta con un errore 400.

Cosa fare:

• Includete testo visibile nel prompt. Se uno script costruisce il prompt da una variabile o file, controllate che la fonte non sia vuota prima di chiamare Claude Code.

L'input stream-json ha superato 256M caratteri senza newline

Il vostro programma ha inviato più di 268.435.456 caratteri su stdin senza newline a un'esecuzione claude -p --input-format stream-json, quindi Claude Code stampa questo errore su stderr ed esce con codice 1 invece di bufferizzare più input. Il messaggio dichiara quel budget come 256M. Prima della v2.1.257, Claude Code bufferizzava tale input senza limiti, facendo crescere la memoria fino a quando il processo si bloccava o veniva ucciso.

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.

L'input così lungo senza newline di solito significa che il produttore non è affatto un produttore stream-json, come un file binario o output di log semplice pipato per errore. Un singolo messaggio oltre il budget fallisce lo stesso controllo.

Cosa fare:

• Controllate cosa è pipato su stdin. Con --input-format stream-json, ogni messaggio deve essere una riga JSON terminata da newline
• Per inviare testo semplice invece, eliminate --input-format stream-json; claude -p legge un prompt di testo semplice da stdin per impostazione predefinita

Comando sconosciuto

In una sessione terminale interattiva, avete inviato un nome / che non corrisponde a nessun comando in questa sessione, quindi Claude Code segnala il nome invece di eseguire qualsiasi cosa:

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

Claude Code suggerisce il nome di comando o alias più vicino che il menu elenca in questa sessione. Quando nulla è vicino, il messaggio termina dopo il nome. La causa è di solito una delle seguenti:

• Un errore di battitura, come /hepl per /help. How the command menu matches what you type copre la scelta di una corrispondenza vicina prima di inviare
• Un comando che esiste ma non è disponibile in questa sessione perché un requisito non è soddisfatto, come la vostra piattaforma, piano o metodo di autenticazione. Le voci di risoluzione dei problemi per /web-setup e /schedule illustrano due casi comuni. Alcuni comandi rispondono con il loro messaggio quando la politica della vostra organizzazione li disabilita, come Cloud sessions are disabled by your organization's policy
• Un comando da un plugin o server MCP che non è installato o connesso in questa sessione

Claude Code risponde a un nome / non corrispondente in questo modo solo in una sessione terminale interattiva. In ogni altra sessione, invia il prompt a Claude come messaggio normale invece, con una nota che il comando non è stato eseguito e un elenco di comandi che Claude può eseguire nella sessione. Quelle sessioni includono:

• Esecuzioni -p
• Applicazioni Agent SDK
• La scheda Code dell'app Desktop
• Il pannello chat dell'estensione VS Code
• Sessioni cloud e routine

Per un comando integrato che non può essere eseguito in una di quelle 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 un nome non corrispondente a Claude. Prima della v2.1.273, rispondevano anche Unknown command.

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

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

Cosa fare:

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

Il diff è troppo grande per ultrareview

Il diff tra il vostro ramo e il ramo base, incluse le modifiche non committate e staged, 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 utilizza un'esecuzione gratuita e non fattura i crediti di utilizzo. Il messaggio nomina i limiti in vigore, la dimensione del vostro diff e i file che contribuiscono il maggior numero di righe modificate. Prima della v2.1.216, il messaggio mostrava solo le statistiche di diff grezze.

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 PR #<N> is too large for ultrareview e nomina i conteggi di file e righe della PR.

Cosa fare:

• Passate un ramo base più vicino al vostro lavoro, come /code-review ultra develop, in modo che la revisione copra solo il diff rispetto a quel ramo
• Dividete la modifica in rami più piccoli e revisionate ognuno. I file che il messaggio nomina contribuiscono il maggior numero di righe modificate, quindi iniziate spostando quelli nel loro ramo.

Non è stato possibile trovare merge-base con il ramo base

/code-review ultra e il sottocomando claude ultrareview revisione il diff tra il vostro ramo e un ramo base, che ha bisogno di un commit che i due condividono. 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 è completo, con almeno un ramo, ricade a revisione di ogni file tracciato invece di rifiutare. Vedete questo rifiuto quando il ramo base non può essere trovato affatto, quando Claude Code non può verificare che il vostro clone è completo, o nel raro repository dove il diff dell'intero albero non è possibile, come il formato di oggetto 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 cosa Claude Code ha osservato:

• Non avete passato un ramo base: Claude Code ha confrontato rispetto al ramo predefinito del repository e suggerisce di passare il vostro base esplicitamente, come nell'esempio sopra
• Avete passato un ramo base che era già nel vostro clone: il suggerimento legge Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)
• Avete passato un ramo base che non era nel vostro clone: Claude Code lo ha recuperato da origin prima di confrontare. Il suggerimento legge <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 può dire se il vostro clone è superficiale, suggerisce git fetch --unshallow origin invece. Prima della v2.1.221, il suggerimento suggeriva git fetch --unshallow origin per ogni ramo 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 ramo è il vostro vero base, passatelo esplicitamente: /code-review ultra <branch>
• Se il vostro clone potrebbe non avere la cronologia completa, eseguite git fetch --unshallow origin e rieseguite la revisione

Il vostro checkout non ha rami

Un checkout può avere commit ma nessun ramo: se eseguite git init seguito da git fetch <url> e git checkout FETCH_HEAD, ottenete un HEAD staccato senza ref. Claude Code pacchetto il vostro repository come un bundle git per caricarlo per un ultrareview, e non può pacchetto un repository che non ha rami 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 revisione ogni file tracciato in questo checkout, e il caricamento falliva.

Cosa fare:

• Create un ramo al vostro commit corrente con git checkout -b <name>, quindi rieseguite la revisione

Nessun account GitHub è connesso al vostro account Claude

Avete 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 connesso al vostro account Claude può raggiungere il repository della PR. Nessun account è connesso, o la connessione è scaduta, quindi il clone cloud fallirebbe e Claude Code rifiuta il lancio. Claude Code non spende un'esecuzione gratuita o fattura i crediti di utilizzo per un lancio 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 vostra sessione, il messaggio nomina solo il link claude.ai.

Cosa fare:

• Eseguite /web-setup per connettere il vostro login GitHub CLI al vostro account Claude, oppure connettete un account su claude.ai/connect-github
• Rieseguite la revisione un minuto dopo la connessione

Prima della v2.1.248, Claude Code non controllava questo prima del lancio.

Il vostro account GitHub connesso non riesce a vedere il repository

Avete eseguito /code-review ultra <PR#> o claude ultrareview <PR#>, e l'account GitHub connesso al vostro account Claude non riesce a leggere il repository della PR, quindi il clone cloud fallirebbe e Claude Code rifiuta il lancio. Claude Code non spende un'esecuzione gratuita o fattura i crediti di utilizzo per un lancio 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 vostra sessione, il messaggio nomina solo l'installazione dell'app.

Cosa fare:

• Se il vostro CLI gh locale riesce a leggere il repository, eseguite /web-setup per connettere quel login al vostro account Claude
• Rieseguite la revisione dopo la modifica

Prima della v2.1.248, Claude Code non controllava questo prima del lancio.

Il preflight dell'app GitHub ha fallito transientemente

Avete avviato una sessione cloud da un repository locale, e due passaggi hanno fallito insieme. Claude Code non ha potuto costruire o caricare il bundle del vostro repository. Prima del caricamento, ha controllato se il servizio cloud può clonare il repository da GitHub, e piuttosto che una risposta definitiva, quel controllo è terminato in un errore che un nuovo tentativo potrebbe cancellare, come un errore di rete, un timeout o un errore di server temporaneo. Il messaggio completo inizia con cosa ha fermato il bundle, ad esempio Could not upload repo bundle (<error>), e termina con la frase di preflight:

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:

• Rieseguite il comando dopo un momento. Quando il controllo GitHub passa, Claude Code può avviare la sessione da un clone GitHub, quindi il caricamento fallito non blocca più il lancio
• Se i nuovi tentativi continuano a fallire, l'inizio del messaggio nomina cosa ha fermato il caricamento. Quando quella causa è qualcosa che potete correggere, correggete in modo che la sessione possa avviarsi dal vostro repository locale invece

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 transientemente, e il consiglio di configurazione non può cancellare un fallimento transitorio.

Il caricamento del repository non può seguire un'impostazione git

Avete avviato una sessione cloud che carica il vostro repository locale, o un ultrareview di un ramo, e il caricamento non può seguire una delle impostazioni git che decidono quali regole di attributo si applicano ai vostri file. Se il caricamento fosse andato avanti e avesse perso una regola, un file che git trasforma prima di memorizzarlo, come uno che un filtro pulito crittografa, potrebbe raggiungere il cloud come è su disco. Claude Code rifiuta il caricamento invece, e nulla viene caricato:

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 nomina l'impostazione e dove è impostata, e termina con la correzione per il caso che avete colpito. Lo stesso rifiuto appare per core.attributesFile e attr.tree, ognuno con la sua correzione.

Il messaggio può nominare un file di configurazione che la vostra configurazione git tira in attraverso una direttiva include o includeIf, anche quando la condizione di quella direttiva non si applica a questo repository.

Cosa fare:

• Applicate la correzione nella frase finale del messaggio

GitHub non è connesso al vostro account Claude

Avete avviato una sessione cloud dal vostro repository locale, ad esempio con /autofix-pr. Nessun account GitHub è connesso al vostro account Claude, o la connessione è scaduta, quindi Claude Code rifiuta il lancio:

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 create una routine con /schedule, lo stesso messaggio appare come una nota di configurazione che nomina il repository; la nota non blocca la creazione della routine.

Cosa fare:

• Eseguite /web-setup per connettere il vostro login GitHub CLI al vostro account Claude, oppure connettete un account su claude.ai/connect-github. Vedete GitHub authentication options per come i due differiscono.
• Rieseguite il comando un minuto dopo la connessione

Prima della v2.1.268, Claude Code segnalava questo come un fallimento temporaneo del controllo dell'app GitHub di Claude e suggeriva di riprovare o installare l'app; nessuno dei due connette un account GitHub.

Autorizzazione single sign-on necessaria

Avete eseguito /install-github-app e scelto un repository la cui organizzazione applica il single sign-on SAML. Prima della configurazione, Claude Code controlla il vostro accesso al repository con la CLI GitHub, e GitHub ha rifiutato quel controllo perché il vostro token gh non è ancora autorizzato per l'organizzazione. La procedura guidata mostra l'avviso con i passaggi per autorizzare:

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:

• Riautorizzate il vostro login GitHub CLI con gli ambiti repo e workflow eseguendo gh auth refresh -h github.com -s repo,workflow, e autorizzate l'organizzazione quando GitHub chiede il single sign-on
• Se vi autenticate con un token di accesso personale in GH_TOKEN, aprite github.com/settings/tokens, selezionate Configure SSO sul token, e autorizzate l'organizzazione
• Eseguite di nuovo /install-github-app

Prima della v2.1.273, Claude Code mostrava l'avviso Admin permissions required per questa condizione invece.

Impossibile riprendere la conversazione

Claude Code non ha potuto leggere o elaborare la trascrizione salvata per la sessione che avete selezionato dal picker claude --resume, quindi termina il processo piuttosto che continuare in uno stato parzialmente caricato. 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 picker /resume dentro una sessione in esecuzione segnala Failed to resume conversation nella conversazione invece, e la vostra sessione corrente continua a funzionare. Prima della v2.1.216, una ripresa fallita dal picker claude --resume rimaneva sullo spinner Resuming conversation… indefinitamente invece di mostrare questo messaggio.

Cosa fare:

• Eseguite claude --resume <session-id> con l'ID della sessione dal messaggio per riprovare
• Se ogni nuovo tentativo fallisce allo stesso modo, eseguite claude update e riprendete di nuovo. Le versioni prima della v2.1.275 falliscono la ripresa quando la trascrizione salvata contiene una voce che non riescono a leggere.
• Se il nuovo tentativo fallisce di nuovo, eseguite claude per avviare una nuova sessione

Nessuna conversazione trovata con l'ID della sessione

Avete passato un ID della sessione a claude --resume <session-id> e nessuna trascrizione salvata lo ha abbinato:

No conversation found with session ID: <session-id>

Claude Code esce con codice 1 dopo aver mostrato il messaggio. Claude Code cerca prima il progetto corrente, quindi ogni altro progetto su questa macchina per l'ID. Prima della v2.1.223, la ricerca si fermava alla directory del progetto corrente e ai suoi git worktrees, quindi riprendete dalla directory in cui la sessione ha lavorato l'ultima volta.

Cause comuni:

• ID digitato male: per un'esecuzione non interattiva, l'ID è il campo session_id dell'output --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 riprendete la sessione sulla macchina dove è stata eseguita
• Copie duplicate: se avete copiato una directory di progetto sotto ~/.claude/projects in modo che due trascrizioni portino lo stesso ID, Claude Code segnala questo messaggio piuttosto che riprendere una copia arbitrariamente

Cosa fare:

• Per una sessione interattiva, aprite il picker della sessione con claude --resume e premete Ctrl+A per allargarlo a ogni progetto su questa macchina, quindi selezionate la sessione
• Le sessioni create con claude -p o l'Agent SDK non appaiono nel picker, quindi controllate di nuovo l'ID rispetto al session_id che la vostra esecuzione originale ha stampato

Windows ha segnalato un errore (EBADF) quando Claude Code ha letto il file di trascrizione di questa sessione

Avete ripreso una sessione su Windows, il suo file di trascrizione salvato si è aperto normalmente, e la lettura ha quindi fallito con l'errore di sistema EBADF. L'errore di sistema non dice perché la lettura ha fallito, quindi il messaggio suggerisce 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 fallimento 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 dentro una sessione, la vostra sessione corrente continua a funzionare.

Cosa fare:

• Escludete la cartella che contiene le vostre trascrizioni di sessione dal software che scansiona o intercetta le letture di file, come strumenti di sicurezza, crittografia o gestione degli endpoint. Le trascrizioni vivono sotto %USERPROFILE%\.claude\projects per impostazione predefinita, o sotto la directory che CLAUDE_CONFIG_DIR nomina
• Se non potete aggiungere un'esclusione, aggiungete Claude Code alle applicazioni consentite di quel software invece
• Riprendete la sessione di nuovo

Prima della v2.1.282, il fallimento veniva senza spiegazione: claude --resume <session-id> terminava a 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.

Impossibile cambiare renderer in questa sessione

Quando cambiate renderer, Claude Code riavvia il suo processo. Avete eseguito /tui in una sessione che Claude Code rifiuta di riavviare, quindi non cambia e non salva nulla. Quale messaggio vedete vi dice la causa:

• Cannot switch renderers while work is running in the background: avete lavoro in background in esecuzione che un riavvio abbandonarebbe, come una shell in background o un subagente. Aspettate che il lavoro finisca o fermatelo con /tasks, quindi eseguite 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 riavviava comunque e la sessione riavviata veniva eseguita senza di esse

Nel messaggio delle restrizioni, la parte tra parentesi nomina le restrizioni che Claude Code ha trovato:

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: avete avviato la sessione con un flag che Claude Code non passa di nuovo al processo riavviato. Questi flag includono --system-prompt, --system-prompt-file, --append-system-prompt-file, un allowlist --tools, --setting-sources e --permission-prompt-tool
• permission rules set for this session only: un aggiornamento di permesso da un hook o da un chiamante SDK ha aggiunto regole di negazione o richiesta con la destinazione session. Le regole di permesso di sessione con ambito di sessione non attivano il rifiuto. Un riavvio le elimina, e Claude Code chiede di nuovo invece
• ask-before-running rules with no command-line form: un aggiornamento di permesso da un hook o da un chiamante SDK ha aggiunto regole di richiesta insieme alle regole che Claude Code passa di nuovo come --allowed-tools e --disallowed-tools. Nessun flag esiste per le regole di richiesta
• permission rules a command line cannot carry intact e added directories a command line cannot carry intact: un aggiornamento di permesso ha aggiunto una regola o un percorso di directory a metà sessione. La riga di comando del processo riavviato non può portare il suo testo come lo stesso valore

Cosa fare:

• In una sessione avviata senza quelle restrizioni, eseguite /tui fullscreen, o /tui default per cambiare di nuovo. Claude Code salva l'impostazione tui lì

Non è stato possibile aprire Claude Desktop

Avete eseguito /desktop o il suo alias /app in una sessione, o claude --desktop nella vostra shell, e il comando di sistema che Claude Code utilizza per aprire Claude Desktop ha fallito. Dopo /desktop, la sessione rimane nel terminale; claude --desktop stampa il messaggio senza il prefisso Error: ed esce con stato 1.

Il testo tra parentesi nomina il comando che ha fallito, con il suo stato di uscita e la prima riga del suo output di errore quando lo ha prodotto. 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:

• Aprite Claude Desktop voi stessi, quindi eseguite di nuovo /desktop o claude --desktop
• Per leggere l'output di errore completo del comando fallito, attivate la registrazione di debug con /debug ed eseguite di nuovo /desktop, oppure eseguite claude --desktop --debug-file <path>, quindi controllate il log di debug

Prima della v2.1.285, il messaggio terminava 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 diceva cosa ha fallito.

/terminal-setup ha lasciato la vostra mappa di tasti Zed invariata

Avete eseguito /terminal-setup in Zed, e Claude Code non ha potuto completare l'aggiornamento al vostro Zed keymap.json, quindi ha lasciato il file come era.

Ogni messaggio nomina il percorso della vostra mappa di tasti e termina con il blocco di scorciatoie da tastiera da aggiungere voi stessi:

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 nomina la causa:

• Couldn't read your Zed keymap, so it was left unchanged.: Claude Code non ha potuto leggere il file, ad esempio a causa di permessi di file
• Your Zed keymap isn't a readable list of keybindings, so it was left unchanged.: il file è stato letto bene ma non viene analizzato come un array di blocchi di scorciatoie da tastiera, anche con commenti // e virgole finali consentite
• Couldn't back up your Zed keymap; not modifying it.: Claude Code non ha potuto copiare il file in un backup .bak accanto ad esso, quindi non ha cambiato nulla
• Couldn't update your Zed keymap, so it was left unchanged.: il risultato unito non ha verificato come una mappa di tasti valida che porta la scorciatoia da tastiera, quindi Claude Code lo ha scartato invece di scrivere. Un blocco di scorciatoia da tastiera con una chiave duplicata può causare questo

Cosa fare:

• Copiate il blocco dal messaggio nell'array di livello superiore nel vostro keymap.json al percorso che il messaggio nomina
• Per isn't a readable list of keybindings, correggete l'errore di sintassi, o rendete il valore di livello superiore del file un array, quindi eseguite di nuovo /terminal-setup

Prima della v2.1.247, /terminal-setup non poteva analizzare una mappa di tasti Zed che utilizzava commenti // o virgole finali, e sostituiva l'intero file con solo la sua scorciatoia da tastiera mentre segnalava la scorciatoia da tastiera come installata. Per ripristinare una mappa di tasti che una versione precedente ha sostituito, utilizzate il file di backup .bak descritto sotto Enter multiline prompts.

I rapporti di utilizzo delle skill non sono disponibili su questa connessione

Avete eseguito /skill-doctor su Remote Control, dal vostro telefono o browser. Claude Code non invia il rapporto di utilizzo delle skill su Remote Control e risponde con questo messaggio invece:

Skill usage reports are not available on this connection.

Cosa fare:

• Eseguite /skill-doctor nel terminale sulla macchina dove la sessione è in esecuzione, oppure eseguite claude -p "/skill-doctor" lì

Gli stili di output personalizzati non possono essere selezionati su Remote Control

Avete eseguito /output-style dall'app mobile o web tramite Remote Control, o il comando è arrivato in un messaggio inoltrato nella sessione. Poiché tale turno potrebbe non provenire dal proprietario dell'account, Claude Code elenca e seleziona solo stili integrati su di esso, e aggiunge questo avviso ogni volta che il comando elenca gli stili o non riconosce il nome che avete dato. Un nome di 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:

• Scegliete uno stile integrato, ad esempio /output-style concise
• Per utilizzare uno stile personalizzato, impostate outputStyle nel .claude/settings.local.json del progetto, oppure eseguite /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

Avete provato a cambiare stili di output con /output-style <style> o /config outputStyle=<style> in una sessione le cui fonti di impostazione escludono local. Gli esempi sono una sessione Agent SDK il cui settingSources lascia fuori "local" e una sessione CLI avviata con un valore --setting-sources che lascia fuori local. Entrambi i comandi salvano lo stile a .claude/settings.local.json, un file che tale sessione non legge mai di nuovo, quindi Claude Code rifiuta invece di 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:

• Aggiungete local alle fonti di impostazione della sessione e cambiate di nuovo
• Impostate 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, impostate outputStyle dentro l'oggetto settings inline invece; vedete Activate an output style

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 dagli strumenti integrati di Claude. Claude corregge la maggior parte degli errori degli strumenti autonomamente. Quando uno richiede una modifica da parte vostra, l'elenco Cosa fare di quell'errore specifica cosa cambiare.

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 vostre 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 elencate Agent, il messaggio lo segnala nel gruppo successivo.
• Matched no tools in this session: la voce è valida ma nessuno strumento nella sessione corrente la corrisponde in questo momento, come mcp__github__* senza server MCP GitHub connesso, o Agent per un subagent al limite di profondità.

Omettere il campo tools non attiva mai questo rifiuto. Se lasciate 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:

• Correggete ogni voce che l'errore nomina rispetto agli strumenti disponibili per i subagent
• Rimuovete le voci per gli strumenti che la sessione non ha, come gli strumenti MCP da un server che non è connesso
• Per uno strumento che i subagent in background eliminano, come CronCreate, rimuovete la voce. Per mantenere lo strumento, disattivate la fork mode e chiedete a Claude di eseguire il subagent in foreground
• Eliminate 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, aumentate il limite di profondità o date all'agent almeno uno strumento aggiuntivo: Claude Code trattiene Agent a quel limite, quindi un elenco con nient'altro in esso 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 cambiano il contenuto che Claude deve essere in grado di leggere di nuovo, 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 con and cannot be written invece.

Cosa fare:

• Se Claude dovrebbe essere in grado di modificare il file, rimuovete o restringete la regola di negazione Read in /permissions o nelle impostazioni
• Se il file deve rimanere intatto, mantenete la regola e aggiungete una regola di negazione Edit per lo stesso percorso per bloccare anche lo strumento NotebookEdit

Path cannot contain null bytes

Un argomento di percorso o pattern di una chiamata dello strumento file conteneva un byte null, che i file system e gli strumenti di ricerca non possono accettare. Read, Write, Edit, NotebookEdit, Glob e Grep controllano questo, 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 dello strumento fallisce, Claude vede l'errore, e il turno continua.

Cosa fare:

• Niente da parte vostra: 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 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 ricadere. Questo è il caso in due configurazioni:

• CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 è impostato in modalità non interattiva, che rimuove ogni subagent integrato
• L'agent del thread principale della sessione ha una lista di autorizzazione 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, aggiungete general-purpose alla lista di autorizzazione tools: Agent(...), o disattivate 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 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 viene raggiunto per primo, vengono caricate all'inizio di una sessione, quindi tutto ciò che supera il limite viene eliminato ogni volta che l'indice viene letto. Prima della v2.1.210, un indice oltre il limite veniva silenziosamente troncato al caricamento successivo senza 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 verso i 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 si adattava.

Claude Code consegna l'errore a Claude dopo la scrittura piuttosto che stamparlo come banner nel vostro terminale, quindi potreste notarlo solo nella trascrizione.

Quando la scrittura di Claude avvicina il file a un limite senza superarlo, Claude Code restituisce un promemoria più mite per compattare l'indice invece di questo errore.

Cosa fare:

• Lasciate che Claude riscrivi MEMORY.md, o chiedetegli: mantenete una riga per voce, spostate i dettagli nei file di argomento, e unite o eliminate le voci obsolete
• Per ridurre l'indice voi stessi, vedete Audit and edit your memory

pkill pattern matches the Claude Code process

Un comando pkill in una chiamata dello strumento Bash ha usato un pattern, tipicamente con -f, che corrisponde al processo Claude Code stesso, quindi Claude Code rifiuta il comando invece di lasciarlo terminare la sessione. Claude Code testa il pattern con pgrep prima di eseguire pkill e rifiuta quando il suo 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 uccideva la sessione 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 piuttosto che come banner nel vostro terminale, e Claude di solito regola il comando autonomamente.

Cosa fare:

• Restringete il pattern in modo che corrisponda solo al processo previsto, ad esempio il percorso completo del binario di destinazione piuttosto che una breve sottostringa
• Per interrompere i processi avviati dalla shell corrente, usate 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 ha potuto scrivere un messaggio nella casella di posta di un compagno di squadra sotto ~/.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 agent tiene 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'agent mittente piuttosto che come banner nel vostro 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 del protocollo strutturato del team di agent falliscono allo stesso modo, e l'errore nomina il messaggio non consegnato: quando Claude Code non può scrivere un'approvazione del piano, un rifiuto del piano, una richiesta di arresto, o un rifiuto di arresto, l'errore legge Failed to write the <message> to <name>'s inbox — nothing was sent. L'approvazione del piano in quell'elenco è la decisione del lead che approva il piano di un compagno di squadra; la presentazione del piano del compagno di squadra è il messaggio separato richiesta di approvazione del piano. Quel messaggio e altri due messaggi del protocollo portano il loro proprio testo di messaggio e 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 fino a quando una ritrasmissione 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 dello strumento
• The confirmation could not be written to team-lead's inbox.: l'approvazione dell'arresto stesso ha avuto effetto e il compagno di squadra esce; solo la conferma al lead manca

Quando voi stessi mandate un messaggio a un compagno di squadra, digitando @name seguito dal messaggio nella sessione del lead, lo stesso fallimento appare come una notifica, Couldn't write to @name's inbox — message not sent. Try again., e Claude Code mantiene il vostro testo nella casella del prompt in modo che possiate inviarlo di nuovo.

Cosa fare:

• Chiedete al mittente di rinviare il messaggio; la contesa per il blocco della casella di posta è transitoria e si risolve al nuovo tentativo
• Controllate lo spazio libero su disco, e controllate che ~/.claude/teams e i file sotto di esso siano scrivibili dal vostro utente

Teammate's agent definition was not restored

Claude ha mandato un messaggio a un compagno di squadra del team di agent fermato, e Claude Code l'ha riportato senza riapplicare la definizione del subagent da cui è stato generato, perché il suo file di definizione proveniva da una cartella senza fiducia salvata. L'avviso segue il rapporto di ripresa nel risultato dello strumento dell'agent 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 la soddisfa.

Cosa fare:

• Eseguite claude nella cartella che il debug log nomina e accettate la finestra di dialogo di fiducia. La definizione viene riapplicata la prossima volta che Claude Code riporta il compagno di squadra; non è necessario riavviare la sessione del lead
• Oppure impostate la voce hasTrustDialogAccepted su true in ~/.claude.json, usando la chiave esatta projects["<path>"] che il debug log stampa

Message too large for cross-session delivery

Il messaggio cross-session di Claude a un'altra delle vostre 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 vostro terminale. Nomina entrambe le dimensioni e come fare in modo che il messaggio si adatti:

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.

Rinviare lo stesso testo fallisce allo stesso modo.

Cosa fare:

• Chiedete a Claude di riassumere il messaggio, o di mettere il contenuto in massa in un file e inviare il percorso del file
• Chiedete a Claude di dividere il contenuto su diversi messaggi più brevi

Prima della v2.1.235, Claude Code segnalava un messaggio di dimensioni eccessive come inviato. La sessione ricevente lo eliminava senza leggerlo.

Too many messages to this session just now

Claude ha inviato una raffica rapida di messaggi cross-session a una delle vostre sessioni su questa macchina, e la raffica ha raggiunto ciò che quella sessione accetta nella casella di posta. 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 vostro 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 messaggio, o aspetta prima di inviare di più
• Se avete voi stessi richiesto la raffica, chiedete 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 eliminava senza leggerli.

Cross-session message was dropped at the recipient session's inbox

Claude ha inviato un messaggio cross-session a un'altra delle vostre 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 nomina 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ò coprire diversi messaggi scartati. Allora inizia al plurale, ad esempio Cross-session messages (12) were dropped. Per trovare quale sessione appartiene a un indirizzo, confrontatelo 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 già conteneva tanti messaggi non consegnati da altre sessioni quanti la sua coda consente
• you sent faster than that session accepts: i messaggi della sessione mittente sono arrivati più velocemente di quanto il destinatario accetta da un mittente
• it repeated your previous message: il messaggio era identico a uno che la sessione mittente ha inviato a questo destinatario poco prima
• a relay loop between sessions was cut: il messaggio ha continuato una catena di sessioni che si mandavano messaggi l'una all'altra, e la catena aveva attraversato il destinatario troppe volte o era cresciuta troppo

Cosa fare:

• Assumete che il destinatario non abbia mai visto i messaggi scartati. Claude Code dice lo stesso a Claude, e gli dice di includere qualsiasi cosa che conta ancora in un messaggio successivo invece di rinviare subito
• Se le vostre sessioni si mandano frequenti aggiornamenti l'una all'altra, chiedete a Claude di inviare meno messaggi, più grandi, come un rapporto quando una sessione finisce il suo lavoro
• Per a relay loop between sessions was cut, digitate l'istruzione successiva in una delle sessioni voi stessi. Un messaggio che Claude invia in risposta al vostro prompt inizia una nuova catena

Prima della v2.1.238, la sessione mittente non riceveva alcun rapporto 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 vostre sessioni su questa macchina, controlla che la 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 che Claude invia, 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: nomina il controllo che ha fallito:

• reply target is a symlink: un collegamento simbolico si trova nel percorso della socket della sessione di destinazione. Claude Code non consegna attraverso di esso, perché un collegamento lì potrebbe reindirizzare il messaggio a un endpoint che la sessione di destinazione non ha creato.
• cannot vet reply target: Claude Code non ha potuto ispezionare il percorso di destinazione affatto, 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 nulla è stato inviato
• Se reply target is a symlink si ripete per una sessione, controllate cosa ha creato un collegamento nel percorso della socket di quella sessione, mostrato nel suo /status sotto Peer address

Refusing to read, write, or search a path

Claude Code controlla le regole di permesso di un percorso file, quindi conferma di nuovo quella risoluzione quando lo strumento apre il file o avvia la ricerca. Quando non può confermare che il percorso conduce ancora alla posizione che il controllo ha approvato, Claude Code rifiuta l'operazione invece di seguirla. 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 nomina la sua ragione:

• its symlink resolution changed after permission was checked: un collegamento simbolico lungo il percorso, o in una radice di ricerca Grep o Glob, è stato sostituito tra il controllo di permesso e l'operazione. In un rifiuto di lettura, la frase tra parentesi nomina quale confronto ha fallito.
• its parent-directory symlink resolution changed after permission was checked: una directory che il percorso di scrittura attraversa 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 ha potuto seguire il percorso a una posizione finale su disco, ad esempio perché i collegamenti simbolici su 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 vi indirizza al target del collegamento
• Refusing to write through symlink: <path>. Resolve the symlink and pass the real target path explicitly.: la stessa condizione catturata quando un altro writer apre il file, come una scrittura a un .mcp.json collegato simbolicamente
• 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 ha potuto essere aperta; 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 eliminato il record di approvazione sotto molte operazioni file simultanee prima che lo strumento lo usasse; riprovare esegue un controllo di permesso fresco
• 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 ha potuto risolvere il binario rg a un percorso assoluto, quindi rifiuta le ricerche al di fuori della directory di lavoro piuttosto che eseguirne una che le vostre regole di negazione non coprono

Cosa fare:

• Di solito niente: il rifiuto raggiunge Claude come risultato dello strumento, e l'operazione rifiutata non viene eseguita
• Se un rifiuto di collegamento simbolico si ripete su un percorso, trovate cosa continua a riscrivere un collegamento lì, come uno strumento di build o un file watcher, o chiedete a Claude di usare il percorso risolto del file invece di quello collegato
• Se questo rifiuto appare per ogni file mentre Claude Code viene eseguito su Windows all'interno di un AppContainer o sandbox con token limitato, aggiornate alla v2.1.265 o successiva
• Se un rifiuto di lettura appare su macOS per un file che nulla sta riscrivendo, come uno screenshot trascinato nel prompt, aggiornate alla v2.1.273 o successiva
• Per il rifiuto di ripgrep, installate ripgrep con il vostro gestore di pacchetti in modo che rg si risolva a un percorso assoluto su PATH, o mantenete le ricerche sotto la 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 di permesso potrebbe reindirizzare una lettura o una ricerca a una posizione diversa senza un messaggio. Di questi, solo i rifiuti di scrittura della directory padre, attraverso collegamento simbolico, e 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 sotto la sua directory temporanea. Ogni volta che apre uno di questi file, controlla che il percorso conduca ancora al file che ha creato, senza collegamento simbolico, collegamento fisico aggiuntivo, o directory spostata che lo reindirizza. Questo messaggio significa che quel controllo è fallito, quindi Claude Code ha rifiutato l'operazione piuttosto che 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 nomina il controllo che ha fallito. Ragioni come output symlink was re-pointed, output file identity changed, e not a regular file segnalano tutte la stessa condizione: qualcosa nel percorso dell'output o lungo di esso non è più il file che Claude Code ha creato. Solo alcune ragioni portano una frase To recover:.

Se il controllo fallisce mentre un comando è ancora in esecuzione, Claude Code interrompe il comando, e il suo risultato segnala:

Command killed: its output file was replaced or could no longer be verified

Cosa fare:

• Aggiornate alla v2.1.260 o successiva. Le versioni precedenti a volte mostravano questo messaggio quando nessun collegamento o directory spostata era presente
• Riavviate Claude Code con CLAUDE_CODE_TMPDIR impostato a una directory fresca
• Oppure controllate la directory del vostro progetto sotto la 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 essere lì, rimuovete il collegamento o la directory stessa piuttosto che il target del collegamento, e riavviate Claude Code
• Se il rifiuto si ripete, un processo sta sostituendo, collegando, o rimuovendo voci sotto la directory temporanea di Claude Code mentre la sessione viene eseguita. Impostate CLAUDE_CODE_TMPDIR a una directory che nulla altro gestisce e riavviate

Disk quota or temp filesystem is full

Claude Code salva l'output di ogni comando Bash e PowerShell in un file sotto la sua directory temporanea. Quando un comando esce con un codice diverso da zero e nessun output affatto, Claude Code controlla se il file system che contiene quel file è senza spazio o inode, o se la vostra quota di disco su di esso è esaurita. Se è così, una diagnostica appare nel risultato del comando 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 nomina cosa è esaurito:

• Your disk quota is full ... (EDQUOT): la vostra quota su quel file system è esaurita. Una quota può essere piena mentre 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 vostra quota su di esso, non ha spazio rimasto
• Command output was lost: the temp filesystem at ... is full o ... is out of inodes: il file system ha quasi nessuno spazio libero rimasto, o sta esaurendo gli inode

Cosa fare:

• Eliminate i file che non vi servono più sul file system che contiene la directory temporanea di Claude Code. Per EDQUOT, eliminate i file che contano verso la vostra quota. Per out of inodes, eliminate molti file piuttosto che pochi file grandi, poiché ogni file occupa un inode indipendentemente dalla sua dimensione
• Oppure riavviate Claude Code con CLAUDE_CODE_TMPDIR impostato a una directory su un file system con spazio
• Quindi fate eseguire il comando di nuovo a Claude. L'output che ha stampato è stato perso, non troncato

The source file is not valid UTF-8 text

Claude ha tentato di pubblicare un artifact 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 nomina 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 vi dice comunque di riscrivere il file come UTF-8. Quando più posizioni seguono quella nominata, il messaggio aggiunge un conteggio come (+2 more) dopo la posizione.

Cosa fare:

• Di solito niente: Claude riscrivi il file e pubblica di nuovo
• Se il file è uno che avete scritto o esportato, salvatelo di nuovo come UTF-8, e sostituite ogni U+FFFD con il carattere che un'edizione, incolla, o conversione precedente ha perso
• Per mostrare un U+FFFD intenzionale sulla 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 la pubblicazione invece.

Reading a local file from outside the connected folders in a Cowork session

In una sessione Cowork in esecuzione sulla vostra macchina nell'app Claude Desktop, Claude ha nominato un file locale per un artifact. Claude Code non ha potuto confermare che il file è 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ò nominare un file diverso da come appare. Leggere un file di questo tipo richiede la vostra approvazione, e in una sessione che non può mostrarvi la carta di approvazione, come una impostata per saltare tutte le approvazioni, Claude Code rifiuta la lettura.

Il rifiuto appare nel risultato dello strumento Artifact; quando il file non ha potuto essere esaminato affatto, nomina quel fallimento invece:

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 un file semplice all'interno delle cartelle connesse invece
• Per mettere quel file esatto nell'artifact, copiatelo in una delle cartelle connesse della sessione come file regolare, non un collegamento simbolico, e chiedete di nuovo

WebFetch cannot fetch localhost

Claude ha chiamato WebFetch con un URL il cui hostname non ha un punto, come http://localhost:3000 o un nome intranet semplice come http://wiki/. WebFetch rifiuta questi URL prima di fare 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 punta Claude a curl attraverso 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.

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 uno di questi rifiuti. 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 symlink 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 symlink, quindi queste ortografie non erano bloccate e una scrittura instradata attraverso un symlink 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 symlink committato 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 ramo 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 ramo predefinito del tuo remote origin, purché quel ramo sia estratto nel tuo checkout principale, la directory del repository stesso piuttosto che un worktree.

Cosa fare:

• Per mantenere i commit, spingi il ramo del worktree, o uniscilo al ramo 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 ramo, ai commit non spinti e a qualsiasi modifica non committata. 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: spingi i 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 ramo o i commit, e eliminare di nuovo era rifiutato allo stesso modo: eliminare la sessione senza spingere 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 ramo predefinito estratto nel tuo checkout principale non contava: un ramo che avevi già unito 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 quell'area di lavoro, 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é il fallback al 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, chiedi al tuo amministratore Windows di consentire l'eseguibile Claude Code nella politica di restrizione
• 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 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 provato ad avviare 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 trusted quando si invia una sessione in background

Hai avviato o riavviato una sessione in background in una directory che non hai trusted, e la finestra di dialogo di fiducia dell'area di lavoro 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.

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.

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