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.

[!NOTE]

Claude Code chiama l'API Claude per le risposte del modello, quindi la maggior parte degli errori di runtime si mappano a un codice di errore API sottostante. Questa pagina copre cosa significa ogni errore all'interno di Claude Code e come recuperare. Per le definizioni del codice di stato HTTP grezzo, vedi il riferimento degli errori della piattaforma Claude.

Trova il tuo errore

Abbina il messaggio che vedi a una sezione qui sotto.

Tentativi automatici

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

Claude Code ritenta questi guasti:

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

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

Claude Code non ritenta questi guasti:

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

Cosa vedi mentre Claude Code ritenta o attende

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

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

Waiting for API response

Il banner Waiting for API response · will retry in … · check your network indica che Claude Code ha atteso almeno 20 secondi senza ricevere alcun dato per una richiesta. La richiesta non è ancora fallita: il countdown corre fino al punto in cui Claude Code interrompe la connessione bloccata. Se l'interruzione avviene:

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

Il banner si cancella da solo una volta che i dati riprendono o un tentativo ha successo. Se riappare ad ogni tentativo, trattalo come un network issue. Se ti connetti tramite un gateway, vedi Il banner di attesa compare e scompare dietro un gateway. Prima della v2.1.185, il banner appariva dopo 10 secondi con una formulazione diversa.

Il banner di attesa compare e scompare dietro un gateway

Se il banner Waiting for API response compare e scompare mentre Claude ragiona e ti connetti tramite un gateway, aggiorna Claude Code alla v2.1.309 o successiva. Il banner appare dopo 45 secondi senza dati su queste connessioni:

• ANTHROPIC_BASE_URL impostato su un host diverso dall'API Anthropic, come un LLM gateway
• Una sessione Claude apps gateway
• Claude Platform on AWS con ANTHROPIC_AWS_BASE_URL impostato

Prima della v2.1.309, il banner appariva dopo 20 secondi su queste connessioni.

Sintonizza il comportamento dei tentativi

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

Quanto attende un tentativo non in streaming

Un tentativo non in streaming termina al suo timeout della richiesta o al timeout di inattività del corpo, a seconda di quale arrivi prima:

• Timeout della richiesta: API_TIMEOUT_MS quando imposti un valore positivo, altrimenti 300 secondi in una sessione locale.
• Timeout di inattività del corpo: da 5 a 6 minuti senza una risposta, per quanto alto imposti API_TIMEOUT_MS, dove è attivo e non l'hai disattivato.

Errori del server

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

API Error: 500 Internal server error

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

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

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

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

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

Cosa fare:

• Controlla status.claude.com o la pagina di stato del provider indicata nel messaggio per eventuali incidenti in corso
• Aspetta un minuto, quindi invia di nuovo il messaggio. Il tuo messaggio originale è ancora nella conversazione, quindi per un prompt lungo puoi digitare try again invece di incollarlo tutto.
• Se ANTHROPIC_BASE_URL punta a un gateway LLM e ogni richiesta non riesce in questo modo, verifica che il tuo gateway e il relativo upstream accettino i campi della ricerca degli strumenti. Per impostazione predefinita, Claude Code invia i campi degli strumenti defer_loading e i blocchi tool_reference, con l'intestazione anthropic-beta che li abilita. Prima della v2.1.304, la ricerca degli strumenti era disattivata dietro un gateway a meno che non la attivassi con ENABLE_TOOL_SEARCH.
• Se l'errore persiste senza alcun incidente pubblicato, esegui /feedback in modo che Anthropic possa indagare con i dettagli della tua richiesta. Consulta Segnalare un errore se /feedback non è disponibile nel tuo ambiente.

API Error: Repeated 529 Overloaded errors

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

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

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

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

Cosa fare:

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

• Riprova tra qualche minuto

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

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

Request timed out

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

Request timed out

Il timeout predefinito della richiesta è di 10 minuti. Se imposti API_TIMEOUT_MS su 0, questo timeout della richiesta è disattivato. La scadenza del primo byte e il timeout di inattività del corpo non si disattivano quando imposti 0, quindi una richiesta in streaming viene comunque eseguita con quelli tra questi che si applicano alla tua connessione. Un tentativo non in streaming mantiene il suo limite di 300 secondi in una sessione locale e può comunque terminare con questo messaggio.

Cosa fare:

• Se ogni richiesta non riesce con questo messaggio e hai impostato API_TIMEOUT_MS su 0, controlla claude --version. Su una versione precedente alla v2.1.305, aggiorna Claude Code o imposta un valore positivo.
• Riprova la richiesta
• Se la causa è una rete lenta o un proxy, aumenta API_TIMEOUT_MS come descritto in Nuovi tentativi automatici
• Se i timeout sono frequenti e la tua rete per il resto funziona correttamente, consulta Errori di rete e di connessione più avanti

No response from API

Claude Code ha inviato una richiesta in streaming e l'API non ha restituito intestazioni di risposta entro la scadenza per il primo byte. Claude Code interrompe una richiesta di questo tipo invece di attendere l'intero timeout di richiesta API_TIMEOUT_MS e la invia di nuovo se il budget dei nuovi tentativi lo consente. Quando la scadenza passa anche per il nuovo tentativo, il turno termina con questo messaggio, che mostra quanto ha atteso ciascun tentativo.

Se imposti CLAUDE_CODE_RETRY_WATCHDOG, Claude Code continua a riprovare secondo il budget descritto in Regolare il comportamento dei nuovi tentativi invece di terminare il turno.

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

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

• Primo tentativo: CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS quando lo imposti su 1 o più, limitato a un valore compreso tra 10 secondi e 30 minuti. Altrimenti Claude Code usa il timeout del watchdog a livello di byte indicato in Watchdog di inattività dello streaming, quindi le variabili che modificano quel timeout modificano anche questa attesa. In entrambi i casi, Claude Code aggiunge un secondo per ogni 32KB del corpo della richiesta.

• Nuovo tentativo: un secondo in meno di API_TIMEOUT_MS, poco meno di 10 minuti per impostazione predefinita, in modo che il nuovo tentativo possa durare più a lungo di un proxy o gateway che trattiene la risposta fino al completamento della generazione. Su Amazon Bedrock, il nuovo tentativo usa la stessa scadenza del primo tentativo e il messaggio mostra una sola durata invece di due.

  Tranne che su Amazon Bedrock, se imposti API_TIMEOUT_MS su 0, il nuovo tentativo attende 10 minuti più un secondo per ogni 32KB, oppure quanto il primo tentativo se questo è più lungo.

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

In una sessione Claude apps gateway, questa scadenza è attiva solo quando la attivi impostando CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS su 1 o più.

Cosa fare:

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

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

The response above may be incomplete

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

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

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

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

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

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

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

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

Cosa fare:

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

Auto mode cannot determine the safety of an action

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

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

Quando il modello del classificatore non è disponibile:

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

In una sessione interattiva, sotto la chiamata allo strumento appare una riga attenuata Not run · auto mode's check had no usable answer al posto di questo messaggio. La riga può anche sostituire un messaggio che indica che il server non ha fornito alcun verdetto oppure, al di fuori di una sessione remota, uno che inizia con Auto mode could not evaluate. Premi Ctrl+O per leggere il suo messaggio nel visualizzatore della trascrizione. Prima della v2.1.296, il messaggio appariva come errore in rosso.

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

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

Cosa fare:

• Riprova dopo qualche secondo; Claude vede lo stesso messaggio e di solito riprova da solo. Un errore temporaneo non è legato all'idoneità alla modalità auto; non devi modificare le impostazioni
• Se i nuovi tentativi continuano a non riuscire, prosegui con attività di sola lettura e torna più tardi all'azione bloccata
• Su Amazon Bedrock, se il messaggio si ripresenta a ogni nuovo tentativo, verifica che il tuo account possa invocare il modello indicato: per i modelli Amazon Bedrock standard, conferma che la tua policy IAM ne consenta l'invocazione; per gli ID modello Mantle, contatta il team del tuo account AWS
• Se il messaggio si ripresenta a ogni nuovo tentativo e indica il modello che hai impostato in CLAUDE_CODE_AUTO_MODE_MODEL, verifica che l'API o il provider cloud su cui viene eseguita la tua sessione serva quell'ID modello. In caso contrario, imposta la variabile su un ID modello che serve, oppure rimuovi la variabile per usare il modello del classificatore predefinito.

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

Quando il classificatore ha restituito una risposta non analizzabile:

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

Cosa fare:

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

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

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

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

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

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

Cosa fare:

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

Quando la conversazione è troppo lunga per la richiesta al classificatore di Claude Code e Claude Code non riesce a compattarla da solo:

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

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

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

Cosa fare:

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

The server returned no safety verdict

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

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

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

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

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

Alcuni rifiuti non vengono conteggiati nei dieci, incluso un rifiuto dovuto a una modifica apportata da un hook o da un mod.

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

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

Cosa fare:

• In una sessione interattiva, premi Ctrl+O per leggere il testo del rifiuto nel visualizzatore della trascrizione.
• Se il rifiuto indica (the conversation is too long for the check), esegui /compact al prompt di Claude Code per accorciare la conversazione. Finché la conversazione non è più breve, inviare un altro messaggio produce lo stesso rifiuto. Se hai disattivato la compattazione automatica, riattivala in modo che Claude Code compatti da solo la prossima volta.
• Invia un altro messaggio per far riprovare Claude. Il conteggio delle risposte riparte da zero.
• Se l'interruzione si ripete e le tue richieste passano attraverso un gateway o proxy LLM, verifica se tronca o riscrive le risposte in streaming. La sezione Revisione del classificatore lato server indica quale comportamento del gateway causa i rifiuti, e la guida alla compatibilità dei gateway elenca cosa deve essere inoltrato senza modifiche.
• Imposta CLAUDE_CODE_AUTO_MODE_SERVER=0 prima di avviare Claude Code per usare invece le sue richieste al classificatore. Prima della v2.1.281, Claude Code non leggeva la variabile su una connessione diretta ad Anthropic API.
• Per approvare tu stesso le azioni, esci dalla modalità auto

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

Prima della v2.1.302, su una connessione diretta ad Anthropic API, Claude Code non compattava una conversazione diventata troppo lunga per il controllo del server.

a hook changed this call's input after auto mode reviewed it

Questo rifiuto significa che un hook o un mod ha modificato l'input della chiamata dopo che il server l'ha revisionata, quindi la revisione non copre ciò che verrebbe eseguito. Non si tratta di un giudizio sulla pericolosità dell'azione.

Le chiamate successive nella stessa risposta di Claude possono essere negate con questo motivo:

another call in this response was changed by a hook after auto mode reviewed it, or could not be confirmed unchanged

Claude può quindi inviare di nuovo ogni chiamata negata in modo che il server la revisioni. Se si apre una richiesta di permesso, rispondi. Non devi fare nient'altro, a meno che Claude non dica nella sua risposta che la modalità auto non è riuscita a controllare la chiamata. In quel caso, interrompi la modifica o approva tu stesso la chiamata, e chiedi a Claude di riprovare la chiamata:

• Interrompi la modifica: disattiva l'hook o il mod che ha modificato la chiamata o una chiamata precedente nella stessa risposta di Claude, oppure chiedi al tuo amministratore di disattivarlo. Per cercare un hook, esegui /hooks al prompt di Claude Code. In una sessione del terminale, esegui /plugin per vedere i mod attivi.
• Approva tu stesso la chiamata: passa alla modalità Manual

Was not reviewed and did not run

Un rifiuto was not reviewed and did not run significa che la conversazione è troppo lunga perché il classificatore della modalità auto possa controllare l'azione, quindi l'azione non è stata eseguita. Claude Code restituisce questo messaggio a Claude:

<tool> was not reviewed and did not run: the conversation is too long for auto mode's classifier. Claude Code will try to compact the conversation before the next request; if this action is still needed after that, issue it again and it will be reviewed normally.

Se la compattazione non riesce, le azioni successive che il classificatore non può controllare ricevono uno di altri due messaggi:

• Un rifiuto gave no verdict (the conversation is too long for the check)
• Il messaggio Auto mode classifier transcript exceeded context window

Cosa fare:

• Se la compattazione annunciata dal messaggio riesce, non devi fare nulla.
• Se vedi uno di questi due messaggi, esegui /compact al prompt di Claude Code per accorciare tu stesso la conversazione. Se hai disattivato la compattazione automatica, riattivala in modo che Claude Code compatti da solo la prossima volta.

Agent terminated early due to an API error

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

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

Cosa fare:

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

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

Limiti di utilizzo

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

You've hit your session limit

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

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

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

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

L'utilizzo conta sia per le indennità di sessione che settimanali contemporaneamente. Un singolo picco di attività intensa, come un grande fanout di workflow, 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 riprova 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, Max e Ultra, 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, aggiungi i campi rate_limits a una riga di stato personalizzata, oppure nell'app Desktop fai clic sull'anello di utilizzo.

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, Max e Ultra, 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

Quando il prompt di consenso per i crediti di utilizzo Fable si chiude senza che nessuno 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.2 leggono continuing on Fable 5.2 e Fable 5.2 now uses usage credits. Prima della v2.1.257, il primo messaggio iniziava Fable 5 limit reached.

Questo accade nelle sessioni Remote Control, nelle sessioni in background, nelle sessioni dei membri di un team di agenti e nelle 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 casi dal limite del tuo piano per l'assenza delle intestazioni di quota unificata che una vera risposta di limite porta. A partire dalla v2.1.199 questo viene riprovato automaticamente con backoff prima di essere mostrato, indipendentemente da come ti autentichi. Nelle versioni precedenti, una sessione con accesso tramite abbonamento claude.ai faceva fallire il turno alla prima occorrenza; solo gli accessi con chiave API ed Enterprise riprovavano.

Cosa fare:

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

Request rejected (429)

Hai raggiunto il rate limit 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 dimenticato 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 sui rate limit per come funzionano i livelli e come impostare i limiti per workspace
• Riduci la concorrenza: evita di eseguire molti subagent in parallelo, 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 https://claude.ai/settings/usage?from=cc_cli_limit_message
You've hit your individual spend limit · ask your admin for a higher limit
You've hit your org's monthly spend limit · visit https://claude.ai/admin-settings/usage to raise it
You've hit your team's shared budget · ask your admin to raise it at https://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 dell'unico 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.

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

Cosa fare:

• Su Pro, Max e Ultra, 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 Organization 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 invece aspettare
• 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 raggiunto un limite di spesa impostato dall'operatore del gateway. Il gateway blocca le tue richieste finché l'operatore non aumenta il limite, oppure finché il limite non si ripristina se è superiore a $0. Contrassegna ogni risposta 429 bloccata con x-should-retry: false, quindi nel terminale Claude Code mostra questo messaggio senza riprovare.

spend limit reached · resets Dec 1

Controlla se il messaggio contiene una data:

• Con una data: il limite si ripristina alle 00:00 UTC di quella data
• Senza data: il tuo limite è $0, oppure il tuo gateway esegue una versione precedente alla v2.1.225

Qualsiasi altro testo nel messaggio è una nota dell'operatore del gateway.

Dalla v2.1.225 fino alla v2.1.319 sul server del gateway, il messaggio nominava il periodo del limite e l'ora di ripristino, come in spend limit reached (daily; resets 2026-08-09 00:00 UTC).

Cosa fare:

• Se il messaggio contiene una data, attendi il ripristino, oppure segui la nota dell'operatore se il messaggio ne contiene una
• Chiedi al tuo operatore del gateway di aumentare il limite se il messaggio non contiene una data, se sei ancora bloccato dopo la data, o se raggiungi il limite regolarmente

Un secondo messaggio del gateway, This request exceeds your group's budget, significa che il budget in pool del tuo gruppo è esaurito. Segui i passaggi che indica:

This request exceeds your group's budget. Ask your organization's admins to raise it, or try again after it resets on November 1 at 00:00 UTC.

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, avvisa il 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, Ultra, 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 esaurisca 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 riprovare con lo stesso valore fallisce di nuovo. Quando il fallimento non ha un motivo fornito dal server, come una connessione interrotta, il messaggio dice Could not update your spend limit. Press Enter to retry. e riprovare 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, riprova; il fallimento potrebbe essere transitorio
• Se la modifica continua a fallire, effettuala invece dalle tue impostazioni di fatturazione claude.ai nel browser

Errori di autenticazione

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

Not logged in

Non è disponibile alcuna credenziale valida per questa sessione.

Not logged in · Please run /login

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

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

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

Cosa fare:

• Esegui /login per autenticarti con il tuo abbonamento Claude o con il tuo account Console
• Se ti aspettavi che una variabile d'ambiente ti autenticasse, verifica che ANTHROPIC_API_KEY sia impostata ed esportata nella shell da cui hai avviato claude
• Per CI o automazioni in cui l'accesso interattivo non è possibile, configura uno script apiKeyHelper che recuperi una chiave all'avvio
• Se i job claude -p terminano con questo messaggio quando qualcuno accede di nuovo allo stesso account e organizzazione claude.ai, aggiorna Claude Code dove viene eseguito quell'accesso. Prima della v2.1.318, Claude Code rimuoveva l'accesso salvato durante quell'accesso, prima di salvare quello nuovo.
• Consulta Precedenza dell'autenticazione per capire quale credenziale usa Claude Code quando ne sono presenti diverse

Se ti viene chiesto ripetutamente di accedere, consulta Not logged in or token expired per i controlli dell'orologio di sistema e i passaggi di ripristino dell'archiviazione delle credenziali su macOS.

Could not resolve authentication method

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

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

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

Cosa fare:

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

Invalid API key

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

Invalid API key · Fix external API key

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

Cosa fare:

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

Your apiKeyHelper script is failing

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

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

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

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

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

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

Cosa fare:

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

Claude Code didn't send your claude.ai login

Questi messaggi indicano che Claude Code ha rifiutato la tua richiesta e non ha inviato il tuo accesso claude.ai:

Your organization's settings need an update. Ask your administrator to fix the API key helper configuration.
Couldn't load your organization's settings. Check your connection, then restart Claude Code.
Restart Claude Code to finish signing in.

Cosa fare:

• Your organization's settings need an update: chiedi al tuo amministratore di correggere la configurazione dell'helper della chiave API
  • Per comunicare al tuo amministratore quali fonti gestite sono presenti sulla tua macchina, esegui /status al prompt di Claude Code e copia la riga Setting sources. Se compare una riga Skipped sources, copia anche quella
  • Se amministri le impostazioni e l'helper si trova nel file di impostazioni gestite o nel criterio MDM di una macchina, consulta Quando l'apiKeyHelper di una macchina non è in vigore
• Couldn't load your organization's settings: controlla la connessione, quindi riavvia Claude Code. Se il messaggio ricompare dopo un riavvio, informa il tuo amministratore
• Restart Claude Code to finish signing in: riavvia Claude Code

Prima della v2.1.315, un prompt o un caricamento di file rifiutato stampava un unico messaggio che iniziava con Claude Code didn't send your claude.ai login.

Invalid request header value

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

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

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

La prima parte del messaggio dipende dalla provenienza del valore errato:

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

Claude Code segnala una ANTHROPIC_API_KEY errata intercettata da questo controllo come Invalid API key, con la stessa descrizione finale. Segnala invece una credenziale /login salvata errata come Not logged in; esegui /login per salvarne una nuova. L'output di uno script apiKeyHelper non arriva mai a questo controllo: Claude Code lo convalida quando lo script viene eseguito, e un output che un header HTTP non può contenere fallisce con Your apiKeyHelper script is failing.

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

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

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

Cosa fare:

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

This organization has been disabled

Claude Code sta usando una ANTHROPIC_API_KEY obsoleta appartenente a un'organizzazione Console disabilitata. Se hai un accesso con abbonamento salvato, la chiave lo sovrascrive.

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

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

Se esporti una chiave nel profilo della shell o ne carichi una da .env, Claude Code la usa al posto di /login, anche con un abbonamento Pro, Max o Ultra funzionante. In modalità non interattiva (-p), la chiave viene sempre usata quando presente.

Cosa fare:

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

Your organization has disabled API key authentication

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

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

L'ultima forma appare in una sessione eseguita dall'app Claude Desktop, come la scheda Code o Cowork, in cui devi accedere di nuovo dall'app.

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

Cosa fare:

• Se il messaggio nomina ANTHROPIC_API_KEY, rimuovila nella shell corrente ed eliminala dal profilo della tua shell o dal file .env, poi riavvia claude
• Se il messaggio nomina apiKeyHelper, rimuovi l'impostazione apiKeyHelper dal tuo settings.json
• Esegui /login per accedere con il tuo account claude.ai
• Esegui poi /status per verificare che la credenziale attiva sia il tuo abbonamento anziché una chiave API
• Se ti serve l'autenticazione con chiave API per le automazioni, chiedi all'amministratore della tua organizzazione di riattivarla nella Console

Your organization has disabled Claude subscription access

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

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

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

L'Agent SDK e la modalità non interattiva -p la segnalano con il codice di errore oauth_org_not_allowed.

Cosa fare:

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

Scheduled tasks are off for your organization

Le attività pianificate cloud sono disattivate per la tua organizzazione, quindi non puoi crearle né eseguirle. Il messaggio di claude.ai le chiama attività pianificate o routine, ed è seguito da una frase che riguarda il tuo amministratore:

Scheduled tasks are off for your organization. …
Routines are off for your organization. …

Non puoi attivarle con impostazioni locali, variabili d'ambiente o flag della CLI.

Cosa fare:

• Chiedi al tuo Owner Team o Enterprise se può attivare l'interruttore denominato Scheduled tasks (Was Routines) o Routines in Organization settings > Capabilities > Remote sessions

Remote Control richiede l'API Anthropic

La sessione non comunica direttamente con l'API Anthropic, come invece richiede Remote Control.

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

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

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

Cosa fare:

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

Remote Control non è riuscito ad aggiornare il tuo accesso

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

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

Quando Claude Code interrompe Remote Control, mostra il motivo in un avviso e in una riga della trascrizione che inizia con Remote Control disconnected. La tua sessione locale continua a funzionare senza Remote Control. Questa sezione 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 indica la causa nella parte centrale del messaggio:

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

Cosa fare:

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

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

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

Remote Control could not renew this computer's connection

Questo avviso appare nel terminale che esegue claude remote-control quando il server non riesce a usare il tuo accesso claude.ai per rinnovare la credenziale della sua connessione prima che scada. L'ultima frase dell'avviso indica per quanto tempo la credenziale corrente funziona ancora, oppure che è già scaduta:

Remote Control could not renew this computer's connection: claude.ai did not accept the sign-in it uses. Run `claude /login` to sign in again. The connection keeps working for about 26 hours; if it still cannot sign in then, it stops.

Cosa fare:

• Se l'avviso ti dice di eseguire claude /login, apri un altro terminale sulla macchina che esegue il server, esegui lì claude /login e accedi con il tuo account claude.ai
• Se il server non riesce ancora ad accedere una volta scaduta la credenziale della connessione, stampa un errore contenente Poll: Authentication failed (401) e si arresta. Accedi di nuovo come indicato nella seconda frase dell'avviso, poi esegui di nuovo claude remote-control nel terminale in cui il server si è arrestato.

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

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

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

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

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

Cosa fare:

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

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

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

Quando l'app desktop di Claude o un IDE ospita la tua sessione, Claude Code ottiene il token di accesso da quell'app anziché da /login. Quando claude.ai rifiuta quel token, Claude Code ne chiede uno nuovo all'app. Se l'app risponde di non avere un accesso attivo, oppure di avere ora effettuato l'accesso 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 tua sessione locale continua a funzionare senza Remote Control.

Cosa fare:

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

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

OAuth token revoked or expired

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

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

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

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

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

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

Cosa fare:

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

API Error: 401 Invalid authentication credentials

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

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

Cosa fare:

• Se /status mostra una riga API key non contrassegnata come non in uso, una ANTHROPIC_API_KEY approvata è la credenziale attiva e ha la precedenza sul tuo accesso, quindi /login non la sostituisce. Ruota la chiave nella Claude Console, oppure torna al tuo abbonamento eseguendo unset ANTHROPIC_API_KEY, o in PowerShell Remove-Item Env:ANTHROPIC_API_KEY.
• Se /status mostra solo il tuo accesso, esegui /login una volta. Se la credenziale è stata revocata, un nuovo accesso la sostituisce.
• Se lo stesso messaggio ricompare per lo stesso account di accesso, l'account o l'organizzazione non è più attivo. Controlla l'account e l'organizzazione riportati da /status e chiedi all'amministratore della tua organizzazione di ripristinare l'accesso.
• Se ANTHROPIC_BASE_URL punta a un gateway LLM, il testo dopo 401 è il messaggio del tuo gateway anziché quello di Anthropic, e /login non lo modifica. Correggi invece la credenziale che il tuo gateway si aspetta.
• Se ogni richiesta fallisce con un 401 anche quando il tuo gateway ha la credenziale che si aspetta, verifica che il gateway e il suo upstream accettino i campi della ricerca degli strumenti. Per impostazione predefinita, Claude Code invia i campi degli strumenti defer_loading e i blocchi tool_reference, con l'header anthropic-beta che li abilita. Prima della v2.1.304, la ricerca degli strumenti era disattivata dietro un gateway a meno che non la attivassi con ENABLE_TOOL_SEARCH.

Login expired

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

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

Login expired · Please run /login

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

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

Per un messaggio Login expired che termina con or re-authenticate your Anthropic profile, consulta Anthropic profile login expired.

Questo non è lo stesso stato di OAuth token revoked or expired. Quei messaggi segnalano un rifiuto restituito dall'API. Login expired lo genera Claude Code stesso per un accesso che non è già riuscito a rinnovare, quindi non invia alcuna richiesta. Quando il rinnovo fallisce perché è l'account stesso a essere sospeso, e non perché l'accesso è obsoleto, Claude Code mostra invece Your account is on hold.

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

Cosa fare:

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

Could not refresh your login because another Claude Code process is refreshing it

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

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

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

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

Cosa fare:

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

Could not refresh your login: the disk that holds the Claude Code config directory is full

Libera spazio sul disco che contiene la directory di configurazione di Claude Code, poi invia di nuovo il tuo messaggio. Accedere di nuovo non servirebbe finché il disco è pieno, perché un nuovo login non potrebbe essere salvato. La directory di configurazione è ~/.claude nella tua directory home, a meno che tu non abbia impostato CLAUDE_CONFIG_DIR.

Could not refresh your login: the disk that holds the Claude Code config directory (~/.claude by default), or your disk quota on it, is full · Delete files you no longer need on that disk, then try again · Signing in again won't help

In modalità non interattiva (-p) e nell'Agent SDK, il messaggio è:

Failed to refresh OAuth token: the disk that holds the Claude Code config directory (~/.claude by default), or your disk quota on it, is full. Delete files you no longer need on that disk and retry; signing in again won't help

Cosa fare:

• Per uno script, esegui di nuovo il suo comando claude -p
• Se il disco mostra già spazio libero, l'esaurimento della quota disco o degli inode produce lo stesso messaggio. Elimina i tuoi file su quel disco. Se il messaggio si ripresenta, elimina molti file piccoli anziché pochi file grandi, perché ogni file occupa un inode indipendentemente dalle sue dimensioni.

Couldn't save your login

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

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

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

Cosa fare:

• Su macOS, sblocca il portachiavi login, poi esegui di nuovo /login
• Sulle altre piattaforme, esegui di nuovo /login
• Se l'accesso continua a non essere salvato, consulta Not logged in or token expired per il comando di sblocco del portachiavi e gli altri passaggi di ripristino dell'archiviazione delle credenziali

Sign in again to take your previous account or API key off the config file

Questo avviso dopo l'accesso significa che qualsiasi account con cui avevi effettuato l'accesso in precedenza potrebbe essere ancora memorizzato in ~/.claude.json:

Sign in again to take your previous account or API key off the config file.

Anche una chiave API potrebbe trovarsi ancora in ~/.claude.json, se un accesso alla Console ne ha creata una su Linux o Windows.

Cosa fare:

• Esegui claude auth login nella tua shell per accedere di nuovo. Claude Code riprova quindi il salvataggio che rimuove dal file l'account o la chiave API sostituiti.

Your account or API key may still be in the config file

Hai eseguito /logout o claude auth logout, e Claude Code ha disconnesso questo processo ma non è riuscito a confermare che ~/.claude.json non contenga più il tuo account. Il salvataggio non è andato a buon fine, oppure non è stato possibile rileggere il file per verificarlo.

Your account or API key may still be in the config file. Run claude auth logout.

Anche una chiave API potrebbe trovarsi ancora in ~/.claude.json, se un accesso alla Console ne ha creata una su Linux o Windows.

Cosa fare:

• Esegui claude auth logout nella tua shell per riprovare il salvataggio. Quando il salvataggio va a buon fine, il comando stampa Successfully logged out from your Anthropic account.

Couldn't start the local listener that receives the browser sign-in

Ciascuno di questi messaggi di /login, claude auth login o claude setup-token significa che Claude Code non è riuscito ad aprire la porta su 127.0.0.1 a cui il tuo browser restituisce il risultato dell'accesso.

Con l'avviso che inizia con The browser can't return the sign-in to Claude Code automatically, l'accesso prosegue senza quella porta. Non si apre alcun browser e l'avviso appare sopra un URL dove invece puoi accedere:

The browser can't return the sign-in to Claude Code automatically. After you sign in, paste the code shown.

Con il messaggio che include Couldn't start the local listener, l'accesso si è interrotto. Questo accade, ad esempio, quando invii input tramite pipe a claude auth login:

Couldn't start the local listener that receives the browser sign-in. Try again.

Cosa fare:

• The browser can't return the sign-in to Claude Code automatically: non devi correggere nulla prima. Apri in un browser l'URL mostrato sotto l'avviso e accedi. Il browser mostra quindi un codice: incollalo in Claude Code al prompt Paste code here > e l'accesso prosegue da lì.
• Couldn't start the local listener that receives the browser sign-in: esegui di nuovo lo stesso comando. Se si interrompe allo stesso modo, accedi con un token o una chiave API invece che con il browser. Oppure, se hai inviato input tramite pipe a claude auth login, eseguilo in un terminale in modo che possa accettare un codice incollato.
• Per accedere con un token o una chiave API invece che con il browser: se usi un abbonamento claude.ai, esegui claude setup-token su una macchina in cui l'accesso funziona. Poi imposta il token che stampa come variabile d'ambiente CLAUDE_CODE_OAUTH_TOKEN su questa macchina. Altrimenti imposta la variabile d'ambiente ANTHROPIC_API_KEY su una chiave della Claude Console. Precedenza dell'autenticazione spiega come Claude Code sceglie tra le credenziali.
• Per ripristinare il ritorno automatico dal browser: Claude Code deve poter restare in ascolto su 127.0.0.1. Se viene eseguito all'interno di una sandbox, verifica che la policy della sandbox consenta l'ascolto su porte locali, poi accedi di nuovo. Se l'ascolto dovrebbe funzionare in quell'ambiente e l'avviso appare ancora, esegui /feedback in modo che la segnalazione includa i dettagli del tuo ambiente.

Prima della v2.1.305, l'accesso si interrompeva non appena la porta non poteva essere aperta e non mostrava alcun URL a cui accedere. Il messaggio era, ad esempio, Failed to start OAuth callback server: Failed to start server. Is port 0 in use?. In quelle versioni, aggiorna Claude Code e accedi di nuovo, oppure accedi con un token o una chiave API invece che con il browser.

Claude login not accepted

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

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

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

Cosa fare:

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

Artifacts need a claude.ai login

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

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

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

Cosa fare:

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

Administrator policy requires a Cloud gateway sign-in

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

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

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

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

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

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

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

Cosa fare:

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

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

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

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

Your account is on hold

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

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

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

Cosa fare:

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

Anthropic profile login expired

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

Anthropic profile login expired · Re-authenticate your Anthropic profile
Login expired · Run /login to sign in again, or re-authenticate your Anthropic profile

Cosa fare:

• Se il messaggio inizia con Login expired, esegui /login per accedere di nuovo
• Per rinnovare un profilo scritto dall'accesso senza chiave alla Console o da ant auth login della CLI di Claude Platform, esegui /login su una macchina che offre l'accesso senza chiave. Scegli l'account Anthropic Console, poi Sign in with your Console account. Claude Code sostituisce la credenziale scaduta in quel profilo
• Per rinnovare un profilo creato da un altro strumento, accedi di nuovo con quello strumento. Se invece scegli Sign in with your Console account in /login, Claude Code lascia il profilo com'è e crea una chiave API
• Se la credenziale del profilo è stata fornita da un amministratore, chiedigli di emetterne una nuova
• Esegui /status per verificare la fonte di credenziali attiva e il nome del profilo
• Per smettere di usare il profilo, rimuovi ANTHROPIC_PROFILE se l'hai impostata, poi autenticati in un altro modo, ad esempio con /login o ANTHROPIC_API_KEY

L'inizio del messaggio ti dice come Claude Code ha trovato il profilo:

• Quando Claude Code ha individuato il profilo dalla tua directory di configurazione e la sua modalità di autenticazione è user_oauth, il messaggio inizia con Login expired e propone prima /login. Claude Code dà a un /login funzionante la precedenza sul profilo individuato e si autentica quindi con il tuo account claude.ai. Dalla v2.1.234 fino alla v2.1.277, questa forma era Anthropic profile login expired · Run /login to use your claude.ai account instead, or re-authenticate the profile. Prima della v2.1.234, Claude Code mostrava anche in questo caso la forma Re-authenticate your Anthropic profile.
• Quando hai selezionato il profilo con ANTHROPIC_PROFILE, il messaggio inizia con Anthropic profile login expired.

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

Requisito di scope OAuth

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

OAuth token does not meet scope requirement: user:profile

Cosa fare:

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

claude.ai rejected the session token

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

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

Cosa fare:

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

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

MCP server needs you to sign in again

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

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

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

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

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

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

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

Per un server con un header Authorization statico nella sua configurazione:

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

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

In una sessione Cowork sulla tua macchina nell'app Claude Desktop, questi messaggi significano che il server MCP ha rifiutato una credenziale che gli è stata fornita. Correggi quella indicata dal messaggio, poi avvia una nuova attività o chat in Cowork:

MCP server "<name>" rejected the credential from its headersHelper (check the helper, then start a new task or chat)
MCP server "<name>" rejected the Authorization header in its config (update it, then start a new task or chat)

• Credenziale headersHelper rifiutata: verifica che l'helper restituisca una credenziale accettata dal server, poi avvia una nuova attività o chat in Cowork
• Header Authorization rifiutato: aggiorna il valore Authorization sotto headers nella configurazione di quel server, poi avvia una nuova attività o chat in Cowork

Prima della v2.1.302, una sessione Cowork mostrava invece le conclusioni run /mcp to reconnect, sebbene /mcp non sia disponibile lì. Se vedi una conclusione di questo tipo in Cowork, controlla comunque l'helper o aggiorna l'header, poi avvia una nuova attività o chat. Prima della v2.1.273, i casi di accesso scaduto, di headersHelper e di header Authorization mostravano tutti MCP server "<name>" requires re-authorization (token expired).

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

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

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

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

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

Couldn't read the stored credentials for MCP server

Claude Code conserva i tuoi accessi per i server MCP OAuth in un archivio di credenziali. Questo messaggio significa che Claude Code non è riuscito a leggere quell'archivio, quindi una richiesta al server non è stata eseguita:

Couldn't read the stored credentials for MCP server "<name>", so the request didn't run. If your Mac's keychain is locked, unlock it, then try again.
Couldn't read the stored credentials for MCP server "<name>", so the request didn't run. Try again.

I tuoi accessi memorizzati non sono cambiati: riprova quando l'archivio può essere letto, e accedi di nuovo solo se il server te lo chiede.

In un'esecuzione di claude -p o dell'Agent SDK su macOS, il portachiavi può diventare leggibile dopo che una richiesta è già partita senza l'accesso memorizzato. Quella richiesta fallisce con:

A request to MCP server "<name>" was sent without your stored credentials, so the server rejected it. The credentials are available now. Try again.

Cosa fare:

• Se il messaggio ti chiede di sbloccare il portachiavi del tuo Mac, esegui claude doctor nella sessione della shell da cui esegui Claude Code e controlla se il suo report contiene un avviso sul portachiavi:

  • Se il report elenca un avviso che inizia con macOS Keychain is not writable, oppure la tua shell non ha il comando claude, esegui questo comando di sblocco in quella sessione della shell:

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

  • Se il report non elenca alcun avviso sul portachiavi, salta il comando di sblocco

• Riprova dove hai visto il messaggio:

  • Per claude -p, esegui di nuovo il comando
  • In una sessione interattiva, riconnetti il server da /mcp se lì appare come non riuscito, poi chiedi a Claude di riprovare
  • In un'applicazione Agent SDK che resta in esecuzione, chiama reconnectMcpServer() in TypeScript o ClaudeSDKClient.reconnect_mcp_server() in Python, oppure avvia una nuova sessione

• Se il server segnala poi di aver bisogno di autenticazione, Claude Code non ha trovato alcun accesso utilizzabile per quel server. Accedi in modo interattivo: esegui /mcp in una sessione di Claude Code, oppure claude mcp login <name> nella tua shell. In un'applicazione Agent SDK, consulta Autenticazione OAuth2 nell'Agent SDK.

Prima della v2.1.307, un'esecuzione di claude -p o dell'Agent SDK su un Mac con il portachiavi login bloccato segnalava il server come bisognoso di autenticazione invece di mostrare uno dei due messaggi.

MCP server URL is missing or not a valid URL

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

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

Cosa fare:

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

Issuer mismatch in authorization response

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

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

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

Cosa fare:

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

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

Refusing to send credentials to non-https token endpoint

Sul runtime v2, Claude Code invia una richiesta di token MCP OAuth solo a un endpoint del token servito tramite HTTPS o su localhost, 127.0.0.1 o ::1. Questo messaggio significa che l'endpoint del token del server non rientra in nessuno dei due casi, quindi Claude Code si è fermato prima di inviare la richiesta. Ciò accade dopo l'accesso tramite browser, quindi il passaggio nel browser riesce prima, e di nuovo ogni volta che Claude Code aggiorna il token del server.

Nella sua forma completa, il messaggio proviene dall'SDK MCP e cita l'endpoint del token che ha rifiutato. Nel log di debug, segue Error during auth completion: per un accesso o Token refresh failed: per un aggiornamento. Nella tua shell, claude mcp login <name> lo stampa dopo Couldn't complete authentication for "<name>":, e in una sessione, /mcp lo mostra 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 come potenzialmente segreto un URL del server che contiene una query string o un segmento di percorso lungo e dall'aspetto casuale. Per un server di questo tipo, oscura gli errori di accesso generati dall'SDK MCP prima di mostrarli o registrarli nei log. Questo errore appare allora come un nome breve che può cambiare tra una release e l'altra, come io, seguito da from the MCP SDK for e dall'URL del server oscurato. Anche gli altri errori dell'SDK MCP assumono lì la stessa forma. Il messaggio oscurato può corrispondere a questo errore solo quando l'endpoint del token del server usa semplice http:// su un indirizzo diverso da localhost, 127.0.0.1 o ::1.

Cosa fare:

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

AWS credentials expired or invalid

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

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

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

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

Cosa fare:

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

AWS authentication failed

Il tuo 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 il modo in cui segnala un diniego di autorizzazione, come un AccessDeniedException dovuto a un permesso IAM mancante. Claude Code non è in grado di distinguere queste due cause.

Anche un 401 da Amazon Bedrock finisce qui invece che in AWS credentials expired or invalid, perché Amazon Bedrock non segnala un token scaduto come un 401. Un 401 da quell'endpoint proviene in genere da qualcos'altro nel percorso della richiesta, come un proxy aziendale.

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

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

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

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

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

Cosa fare:

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

Google Cloud credentials expired or invalid

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

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

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

Cosa fare:

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

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

Google Cloud authentication failed

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

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

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

Cosa fare:

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

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

Microsoft Foundry authentication failed

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

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

Cosa fare:

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

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

Could not load AWS or Google Cloud credentials

Claude Code non è riuscito a ottenere credenziali utilizzabili dalla catena di provider di credenziali AWS o dalle credenziali predefinite dell'applicazione Google sulla macchina su cui è in esecuzione, quindi nessuna richiesta ha raggiunto il tuo provider cloud. Il dettaglio dopo il · indica la causa specifica, come una sessione SSO scaduta, credenziali predefinite dell'applicazione 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 nell'Agent SDK, il codice di errore strutturato è cloud_credential_error. Prima della v2.1.267, il messaggio mostrava solo il testo di dettaglio dopo API Error:, e il codice strutturato era server_error o unknown.

Cosa fare:

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

AWS default-chain credential resolve timed out

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

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

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

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

Cosa fare:

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

Bedrock setup verification timed out waiting for AWS

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

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

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

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

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

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

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

Cosa fare:

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

Cloud gateway session expired

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

Cloud gateway session expired — run /login to reconnect.

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

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

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

Cosa fare:

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

Sign-in timed out while waiting for you to continue

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

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

Cosa fare:

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

Gateway refused the request

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

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

Cosa fare:

• Chiedi all'amministratore del tuo gateway di esaminare la richiesta. La parte finale API Error: riporta il rifiuto restituito dal gateway
• Per gli amministratori: una regola di controllo degli accessi sul gateway restituisce un 403 che il log di audit registra insieme al motivo, e un diniego di autorizzazione da parte di un servizio upstream viene inoltrato come descritto in Messaggi di errore upstream

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

Errori di rete e connessione

La maggior parte di questi errori significa che una richiesta di rete da Claude Code non ha raggiunto la sua destinazione, oppure qualcosa tra Claude Code e l'API ha alterato la risposta durante il percorso; quando una voce ha anche una causa locale, come una scrittura dell'archivio non riuscita, 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 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 instradi 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.
• Se ANTHROPIC_BASE_URL punta già al tuo gateway e ogni richiesta termina con Connection dropped, controlla che il tuo gateway e il suo upstream accettino i campi della ricerca degli strumenti. Per impostazione predefinita, Claude Code invia i campi degli strumenti defer_loading e i blocchi tool_reference, con l'intestazione anthropic-beta che li abilita. Prima della v2.1.304, la ricerca degli strumenti era disattivata dietro un gateway a meno che non la attivassi con ENABLE_TOOL_SEARCH.
• Assicurati che il tuo firewall consenta gli host elencati in Network access requirements
• I guasti intermittenti vengono ritentati automaticamente

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 d'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 file di impostazioni gestite, una policy MDM o un 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 impostazioni gestite 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.

Claude Code salta il controllo anche su una macchina senza impostazioni gestite quando il tuo ~/.claude/settings.json specifica un gateway con forceLoginMethod e forceLoginGatewayUrl. Prima della v2.1.295, Claude Code eseguiva il controllo in quel caso.

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 nuovo tentativo 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 nuovo tentativo. 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 instradi 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 usare il 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 nuovo tentativo. 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 ripiegano su 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 da un'attività pianificata cloud è 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 errore non è un problema di rete lato client. Le sessioni cloud e le attività pianificate cloud vengono eseguite all'interno di una VM sandbox il cui traffico in uscita attraverso la rete della sessione è filtrato in base all'allowlist dell'ambiente cloud:

• Traffico GitHub e dei connettori: le operazioni GitHub e il traffico dei connettori MCP utilizzano canali separati, motivo per cui possono continuare a funzionare mentre altri host sono bloccati
• Ambiente predefinito: l'ambiente Default utilizza l'accesso Limited con Allow package managers selezionato. Le sue sessioni raggiungono l'allowlist predefinita di registri di pacchetti, API di provider cloud, registri di container e domini di sviluppo comuni.

Cosa fare:

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

• Apri il tuo ambiente per la modifica, o dal modulo dell'attività pianificata cloud o dal environment selector dove avvii sessioni cloud.
• Nella finestra di dialogo Edit cloud environment, seleziona Limited in Network access, quindi aggiungi il dominio bloccato a Allowed domains. Inserisci un dominio per riga. Seleziona Allow package managers per consentire l'allowlist predefinita insieme ai tuoi domini. 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 artefatto attraverso il proxy che hai impostato in HTTPS_PROXY o una proxy variable correlata. Il contenuto dell'artefatto 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'artefatto.
• Se la tua rete consente a Claude Code di raggiungere l'host dell'artefatto 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.

Failed to fetch session from Sessions API

Questo messaggio significa che Claude Code ha trovato la sessione cloud che hai chiesto di portare nel tuo terminale ma non è riuscito a leggerne la cronologia della conversazione dai server di Anthropic, quindi non l'ha aperta:

Failed to fetch session from Sessions API: Failed to fetch session logs

Lo vedi dopo claude --teleport, /teleport, o dopo aver scelto la sessione nell'elenco /tasks. claude --teleport <session-id> lo stampa ed esce con codice 1.

Cosa fare:

• Esegui di nuovo lo stesso teleport. Se fallisce allo stesso modo, segnala il problema

Prima della v2.1.296, Claude Code non ritentava una lettura fallita e, dopo una lettura fallita, poteva aprire la sessione con una conversazione vuota e segnalare il successo invece di stampare questo messaggio.

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 riprenderle. 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 worktree mantenuti sotto questo messaggio, recupera da essi qualsiasi lavoro non committato
• 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 invece un archivio locale 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 elimina progressivamente 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 quando nessuna versione ridotta può essere inviata o un errore di rete o server interrompe il caricamento. Quando Claude Code salva invece un archivio locale, il messaggio significa che non è riuscito a 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

Un messaggio che inizia con Couldn't send feedback significa che il servizio di feedback non ha confermato il rapporto che hai inviato dalla finestra di dialogo /feedback, /bug o /share, o una bozza di feedback in coda. Consideralo come non ricevuto. Quando dopo i due punti segue una frase sulla tua organizzazione, la tua organizzazione rifiuta il feedback.

Il secondo esempio è il rifiuto di un'organizzazione:

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.

Couldn't send feedback: Feedback has not been enabled for your organization. To report a bug, open an issue at https://github.com/anthropics/claude-code/issues. Issues are public, so leave out anything confidential.

Cosa fare:

• Accesso non effettuato: il messaggio continua con : not signed in. Run /login, then retry. Esegui /login, quindi invia di nuovo
• Rifiuto della tua organizzazione: ad esempio : Feedback has not been enabled for your organization. o : Feedback collection is not available for organizations with custom data retention policies. In seguito /feedback può rispondere per sette giorni che è disabilitato dalla policy della tua organizzazione. Una bozza in coda rimane in coda e scade comunque secondo la pianificazione
• Credenziali rifiutate: il messaggio continua con : the sign-in this session uses is not allowed to send feedback o : the server did not accept the credentials this session uses. Esegui /status al prompt di Claude Code per vedere quale login, token o chiave API invia questa sessione
• (request timed out) o (couldn't reach the service) subito dopo Couldn't send feedback: invia di nuovo il rapporto o la bozza in coda. La finestra di dialogo mantiene il tuo testo e il messaggio di una bozza in coda indica The draft is still queued. Se anche altre richieste stanno fallendo, controlla la tua connessione di rete e vedi Unable to connect to API. Se continua a fallire, apri la segnalazione su github.com/anthropics/claude-code/issues
• (server returned <status>), o nessun motivo, subito dopo Couldn't send feedback: lo stato è il codice di risposta del servizio. Il messaggio del servizio stesso lo segue quando ne è stato inviato uno, come in (server returned 403: Access Forbidden). Se continua a fallire, apri la segnalazione su github.com/anthropics/claude-code/issues

Le segnalazioni su github.com/anthropics/claude-code sono pubbliche, quindi quando ne apri una escludi codice, trascrizioni e qualsiasi altra informazione riservata.

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.

Feedback payload too large

Questo messaggio nella schermata di revisione di una bozza di feedback significa che Claude Code non ha alcuna conferma che il servizio abbia accettato la bozza. Consideralo come non ricevuto. La bozza rimane nella tua coda di /feedback, quindi puoi inviarla di nuovo.

Feedback payload too large. Try again without the transcript, or shorten the details.

Cosa fare:

• Nella schermata di revisione, imposta Send transcript su no, quindi invia di nuovo la bozza. Accorciare i dettagli rimuove al massimo 10 KB di testo, che è tutto ciò che i dettagli di una bozza possono contenere.

MCP server connection timed out during a sleep or clock change

Questo messaggio significa che una connessione a un server MCP è andata in timeout e Claude Code ha rilevato che l'orologio di sistema è andato avanti durante il tentativo:

MCP server "<name>" connection timed out. Your computer went to sleep or its clock changed while connecting.

Claude Code non può sapere se il tuo computer è andato in sospensione o se il suo orologio è stato spostato in avanti, quindi il messaggio indica entrambe le possibilità.

Cosa fare:

Connettiti di nuovo al server e mantieni il computer attivo finché il tentativo non termina. Se il server si connette, non c'è nulla da correggere.

• In una sessione interattiva: esegui /mcp, seleziona il server e seleziona Reconnect
• Nella tua shell: esegui di nuovo il comando claude -p, claude mcp list o claude mcp get. Se poi il server fallisce con un messaggio che inizia con Skipping connection (recent failure cached, attendi 15 minuti ed esegui di nuovo il comando.
• In un'applicazione Agent SDK: chiama reconnectMcpServer() in TypeScript o ClaudeSDKClient.reconnect_mcp_server() in Python
• Se il server fallisce di nuovo: se il messaggio è diverso da questo, vedi cosa controllare quando un server MCP non si connette. Se questo messaggio ricompare anche se il computer è rimasto attivo e nulla ne ha modificato l'orologio, vedi Report an error.

Prima della v2.1.307, Claude Code mostrava un messaggio di timeout come MCP server "<name>" connection timed out after <N>ms al posto di questo.

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 is too long

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.
• Se l'errore compare vicino ai 200K token su un modello che ne accetta di più, una causa è un ID modello che Claude Code non riconosce. Claude Code presume una finestra di 200K per un ID di questo tipo, quindi per continuare a lavorare oltre quel punto, indicagli la finestra di contesto reale del modello.
  • Se usi un ANTHROPIC_BASE_URL personalizzato e l'errore inizia con Prompt is too long · automatic compaction failed, imposta la finestra di contesto del modello oppure aggiorna alla v2.1.299 o successiva. Prima della v2.1.299, Claude Code terminava il turno con quel messaggio vicino alla finestra presunta di 200K invece di inviare la richiesta.
• Se l'errore è apparso subito dopo che hai interrotto Claude mentre stava compattando la conversazione, la tua conversazione è invariata e ancora abbastanza grande da richiedere la compattazione. Esegui /compact e invia di nuovo il tuo messaggio. Per evitare che l'errore si ripresenti, aggiorna Claude Code alla v2.1.304 o successiva. Prima della v2.1.304, interrompere in quel momento poteva terminare il turno con questo errore.
• Nella v2.1.305, con molti strumenti MCP e una connessione diretta all'API Anthropic, questo errore può nascondere un errore 400 o 422 dell'API non correlato. Aggiorna Claude Code alla v2.1.306 o successiva per vedere l'errore originale.

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 è cresciuta oltre la finestra di contesto del modello:

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

Dopo un avviso Context exceeds, non devi eseguire nessuno dei due comandi mentre la compattazione automatica è attiva, come da impostazione predefinita:

• Compattazione automatica attiva: invia il tuo prossimo messaggio. Se fallisce ancora con Prompt is too long, consulta quella voce.
• Compattazione automatica disattivata: nella sessione, esegui /compact se l'avviso lo cita, oppure /clear per ricominciare. Finché non ne esegui uno, i messaggi falliscono con Context limit reached, oppure con Prompt is too long nell'output di -p.

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:

• Dopo un avviso sulla finestra di compattazione: in una conversazione con più turni, esegui /compact per riassumere i turni precedenti e liberare spazio. Per ricominciare invece da capo, esegui /clear.
• Per altri modi per ridurre l'utilizzo, vedi Prompt is too long

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

Request too large

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 Image was too large di seguito

Image was too large

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
API Error: an image in the conversation could not be processed and was removed.
An image in the conversation exceeds the dimension limit for many-image requests (3000px). Run /compact to remove old images from context, or start a new session.

La riga could not be processed and was removed significa che l'API ha rifiutato un'immagine nella conversazione, ad esempio una che supera i limiti di dimensione o di risoluzione.

Se uno di questi errori continua a ripresentarsi, aggiorna Claude Code. Nelle versioni precedenti, un errore relativo alle immagini poteva ripetersi per motivi come questi:

• Prima della v2.1.299, in una conversazione lunga con molte immagini, Claude Code poteva rimuovere le immagini che avevi allegato per ultime invece di quella che superava il limite. La riga was removed si ripeteva quindi a ogni turno e Claude non vedeva le tue nuove immagini.
• Prima della v2.1.299, in VS Code, nell'app Desktop e nell'Agent SDK, le immagini allegate mentre Claude stava lavorando non venivano ridimensionate come le altre immagini allegate. Raggiungevano l'API alla loro dimensione originale, causando errori ripetuti relativi alle immagini nelle conversazioni lunghe.
• Prima della v2.1.166, un'immagine incollata poteva rimanere nella conversazione, e lo stesso errore si ripeteva quindi a ogni messaggio successivo

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 3000 pixel quando nel contesto ci sono più di 20 immagini.
• Fai uno screenshot più stretto della regione rilevante invece dello schermo intero
• Per il messaggio dimension limit for many-image requests, esegui /compact nel prompt di Claude Code se il messaggio lo nomina, oppure avvia una nuova sessione con meno immagini

Il messaggio dimension limit for many-image requests mostra il limite in pixel indicato nell'errore dell'API.

Unable to resize image

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.

Request rejected as unprocessable by the model

L'API ha rifiutato la richiesta in quanto il modello non può elaborarla. Il messaggio è quello dell'API stessa.

API Error: 400 Request rejected as unprocessable by the model (too many or oversized images, or unsupported parameters)

Claude Code può rimuovere le immagini e i documenti più vecchi da una richiesta rifiutata e inviarla di nuovo. Prima della v2.1.290, Claude Code non rimuoveva le immagini in caso di questo rifiuto, quindi una sessione lunga che ne aveva accumulate centinaia poteva fallire con questo errore a ogni turno.

Cosa fare:

• Se il messaggio continua a comparire in una conversazione con immagini o documenti, rimuovili tu stesso. Premi Esc due volte per tornare indietro oltre i turni che li hanno aggiunti, oppure esegui /clear per ricominciare da zero.

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.

Extra inputs are not permitted

L'endpoint che ha ricevuto la richiesta ha rifiutato uno dei campi della richiesta come input che non accetta, e il messaggio dell'endpoint nomina quel campo.

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

Claude Code invia campi disponibili solo in beta, come context_management e defer_loading della ricerca degli strumenti, insieme a un'intestazione anthropic-beta che li abilita. Quando un gateway inoltra il corpo ma scarta l'intestazione, l'API vede campi che non riconosce. Quando un gateway inoltra un corpo in formato Anthropic a un upstream con uno schema diverso, quell'upstream rifiuta tali campi. Coppie di intestazioni beta e campi del corpo tratta entrambi i casi.

Cosa fare:

• Se il messaggio contiene context_management: Extra inputs are not permitted, aggiorna Claude Code alla v2.1.304 o successiva. Dopo l'aggiornamento, Claude Code risponde a questo rifiuto inviando la richiesta un'altra volta senza il campo. Prima della v2.1.304, Claude Code non riprovava dopo questo rifiuto.
• Se il messaggio indica defer_loading o tool_reference, aggiorna Claude Code alla v2.1.305 o successiva. Claude Code risponde quindi a questo rifiuto inviando di nuovo la richiesta una volta senza i campi della ricerca degli strumenti.
• Se il tuo gateway scarta l'intestazione, configuralo per inoltrare l'intestazione anthropic-beta. Consulta pass-through delle funzionalità per sapere cosa devono inoltrare i gateway.
• Come fallback, imposta CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 prima di avviare. Disabilita le capacità pre-release copre l'ambito esatto.

Prima della v2.1.302, questo errore poteva anche nominare il campo diagnostics senza che fosse coinvolto alcun gateway. Compariva quando una sessione che aveva già usato l'API Anthropic passava ad Amazon Bedrock o all'Agent Platform di Google Cloud senza un riavvio. Ad esempio, una sessione che hai lasciato aperta passa a Bedrock quando esegui /setup-bedrock in un'altra finestra di Claude Code. In quelle versioni, esegui /clear in quella sessione o riavviala.

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.300, esegui claude update nella tua shell. Prima della v2.1.300, Claude Code non riprovava la richiesta senza i parametri dello strumento rifiutato, quindi questo errore si ripeteva a ogni richiesta che includeva lo strumento.
• 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.

Nome dello strumento MCP oltre 128 caratteri

Un server MCP elenca uno strumento il cui nome completo, come mcp__<server>__<tool>, è più lungo dei 128 caratteri che l'API accetta. Claude Code esclude quello strumento dagli strumenti che invia a Claude, e gli altri strumenti del server continuano a funzionare. In una sessione che avvii con claude --debug dalla tua shell, Claude Code scrive questo messaggio nel log di debug in ~/.claude/debug/<session-id>.txt:

Tool "mcp__<server>__<tool>" is not sent to Claude: its name has <N> characters and the API accepts at most 128

Cosa fare:

• Se mantieni il server, accorcia il nome dello strumento.
• Se il server è nella tua configurazione MCP, assegnagli lì un nome più breve, come db al posto di analytics-database. Quindi aggiorna ciò che fa riferimento al server o ai suoi strumenti con il vecchio nome, come le regole di permesso e i matcher degli hook.
• Se un plugin include il server, il nome completo dello strumento include anche il nome del plugin. Chiedi al manutentore del plugin di accorciare il nome del server o dello strumento.

Prima della v2.1.292, Claude Code inviava comunque lo strumento, e l'API rifiutava ogni richiesta che lo includeva con API Error: 400 ... tools.N.custom.name: String should have at most 128 characters.

tool_use.name oltre 200 caratteri

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

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

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

Cosa fare:

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

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

There's an issue with the selected model

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

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

Cosa fare:

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

Model is not a recognized model id

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 There's an issue with the selected model.

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

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

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

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

Cosa fare:

• Esegui /model senza argomenti per aprire il selettore e scegliere dai modelli disponibili per il tuo account, quindi passa l'alias o l'ID mostrato lì
• Se hai usato un alias che solo una versione più recente di Claude Code supporta, esegui claude update, oppure passa l'ID completo del modello. Il server può comunque richiedere una versione minima di Claude Code per quel modello; vedi Claude Code does not support this model.
• 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.

Model not found

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.

Couldn't confirm model with the API

Hai cambiato modello tramite il metodo setModel() dell'Agent SDK o tramite 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 15 secondi. La sessione mantiene il modello corrente.

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

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

Cosa fare:

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

Errore API durante il controllo del modello selezionato

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

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

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

Cosa fare:

• Agisci sulla spiegazione del server; per un rate limit o uno stato 5xx, attendi e seleziona di nuovo il modello
• I rifiuti con la loro propria dicitura sono coperti dalle voci circostanti, come Model not found e Model is restricted by your organization's settings

Claude Opus is not available with the Claude Pro plan

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

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

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

Cosa fare:

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

Claude Code does not support this model

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:

• Se esegui claude update sul canale di rilascio stable, non ti porta oltre la release stable più recente, che può essere ancora al di sotto del minimo richiesto. Passa al canale latest, quindi aggiorna di nuovo. Se la tua organizzazione blocca il tuo canale o la tua versione tramite impostazioni gestite, chiedi al tuo amministratore di cambiarlo
• 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

Model is restricted by your organization's settings

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

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

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

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

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

Cosa fare:

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

Can't switch to the default model

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

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

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

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

Cosa fare:

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

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

Model switch was blocked by a PreModelSwitch hook

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

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

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

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

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

Couldn't save it as your default

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

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

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

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

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

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

L'advisor è meno capace del modello principale attuale

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

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

Altri messaggi segnalano la stessa condizione:

• In una sessione interattiva, una notifica recita Advisor will not activate on the main model (advisor is less capable); subagents may still use it and may use more tokens · /advisor.
• Quando avvii con il flag --advisor in modalità non interattiva, e l'esecuzione non è una sessione in background, un avviso viene scritto su stderr e l'esecuzione si avvia comunque. Dice "<advisor>" cannot advise "<main model>" (the advisor must be at least as capable as the main model). The advisor will not be used for the main model. Una sessione interattiva scrive quell'avviso solo nel log di debug.

Cosa fare:

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

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

thinking.type.enabled is not supported for this model

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

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

Cosa fare:

• Esegui claude update e riavvia Claude Code. Opus 4.7 ha bisogno della v2.1.111 o successiva. Opus 4.8 ha bisogno della v2.1.154 o successiva. Sonnet 5 ha bisogno della v2.1.197 o successiva. Opus 5 ha bisogno della v2.1.219 o successiva. Opus 5.5 ha bisogno della v2.1.280 o successiva. Sonnet 5.5 ha bisogno della v2.1.284 o successiva
• Sul canale di rilascio stable, l'aggiornamento non ti porta oltre la release stable più recente, che può essere ancora più vecchia di queste versioni. Passa al canale latest, quindi aggiorna
• 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

Effort isn't available with thinking turned off

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

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

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

Cosa fare:

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

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

Il budget di ragionamento supera il limite di output

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

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

Cosa fare:

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

Response exceeded the output token maximum

La risposta di Claude ha raggiunto il numero massimo di token di output consentito dalla richiesta ed è stata troncata in quel punto:

API Error: Claude's response exceeded the ... output token maximum. To configure this behavior, set the CLAUDE_CODE_MAX_OUTPUT_TOKENS environment variable.
API Error: Claude's response exceeded the 64000 output token maximum for a request sent without streaming. The CLAUDE_CODE_MAX_OUTPUT_TOKENS environment variable cannot raise this limit.

La forma che nomina a request sent without streaming significa che una richiesta in streaming è fallita e Claude Code l'ha inviata di nuovo senza streaming, il che limita la risposta a 64.000 token di output. Prima della v2.1.299, una risposta troncata su una richiesta inviata di nuovo in questo modo terminava il turno senza questo messaggio, come se la risposta fosse completa.

Cosa fare:

• Se Claude ha scritto del testo prima che la risposta venisse troncata, rispondi continue in una sessione interattiva per chiedere il resto. Quel testo rimane nella conversazione.
• Se il messaggio dice di impostare CLAUDE_CODE_MAX_OUTPUT_TOKENS, consulta CLAUDE_CODE_MAX_OUTPUT_TOKENS per sapere come viene limitato il valore e Impostare le variabili d'ambiente per sapere dove impostarlo
• Per mantenere ogni risposta sotto il limite, chiedi a Claude l'output in parti più piccole, ad esempio un file o una sezione per risposta

Mancata corrispondenza dei blocchi di uso degli strumenti o di ragionamento

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

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

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

Cosa fare:

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

Invalid data in redacted_thinking block

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

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

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

Cosa fare:

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

Unsupported tool content removed

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

[Unsupported tool content removed]

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

Cosa fare:

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

role 'system' must precede an 'assistant' message

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.

Invalid encrypted_content in search_result block

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.

Se il messaggio include la riga Details: `[reasoning_extraction]`, vedi Le misure di protezione hanno segnalato una richiesta del ragionamento di Claude.

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. Send feedback with /feedback or learn more: https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude

Se il messaggio include la riga Details: `[reasoning_extraction]`, vedi Le misure di protezione hanno segnalato una richiesta del ragionamento di Claude.

Questo messaggio si collega al Cyber Verification Program, che concede l'accesso per il lavoro di cibersicurezza legittimo. I modelli con fallback automatico del modello mostrano un messaggio diverso, senza questo link; su Opus 5.5 e Sonnet 5.5 si apre con <model>'s safeguards flagged this session. Quella sezione spiega anche quando Claude Code cambia invece modello.

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

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.

Se il messaggio che vedi è formulato invece come uno di questi, si tratta della stessa segnalazione su una versione precedente di Claude Code:

• Dalla v2.1.219 alla v2.1.296, il messaggio poteva includere anche Apply to the Cyber Verification Program to reduce these interruptions. prima della frase conclusiva
• Dalla v2.1.203 alla v2.1.218, il messaggio era <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 al centro assistenza. Nelle sessioni interattive, proseguiva con If you were not engaging in a cybersecurity topic, please send feedback via /feedback.
• Prima della v2.1.203, il messaggio era <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 a un modulo di esenzione

Le misure di protezione hanno segnalato una richiesta del ragionamento di Claude

L'API ha rifiutato la richiesta perché le misure di protezione l'hanno segnalata come una richiesta al modello di riprodurre il suo ragionamento interno nella risposta. L'API chiama questa categoria di rifiuto reasoning_extraction, e il messaggio di rifiuto include questa riga:

Details: `[reasoning_extraction]`

Prima della v2.1.234, i messaggi di rifiuto non includevano la riga Details.

Cosa fare:

• Rimuovi o riformula qualsiasi istruzione che chieda a Claude di scrivere il suo ragionamento parola per parola o in un formato fisso, come una sezione <thinking>, una sezione scratchpad o un campo reasoning nell'output JSON. L'istruzione può trovarsi nel tuo prompt o in una personalizzazione che Claude Code carica insieme ad esso, come CLAUDE.md, una skill, il prompt di un subagent, uno stile di output o la descrizione di uno strumento MCP.
• Per verificare se la causa è una personalizzazione, esegui claude --safe-mode nel tuo terminale per avviare una sessione con le personalizzazioni disattivate, quindi invia lo stesso prompt
• Dopo aver modificato una personalizzazione, avvia una nuova sessione
• Per riformulare un prompt che hai già inviato, vedi Riavvolgi e riassumi
• Puoi comunque chiedere a Claude di spiegare la sua risposta. Chiedi una breve spiegazione, le prove alla base di un risultato o un riepilogo delle azioni che ha eseguito. Per leggere i riepiloghi del ragionamento di Claude, vedi showThinkingSummaries.
• Per altri esempi, e per cosa fare se una richiesta riformulata viene comunque rifiutata, vedi Keep reasoning in thinking blocks

Output blocked by content filtering policy

Il filtro dei contenuti di output dell'API ha interrotto la risposta che Claude stava generando. Il testo del messaggio proviene dall'API:

API Error: Output blocked by content filtering policy

Cosa fare:

• Riformula il tuo ultimo messaggio o adotta un approccio diverso
• Per tornare indietro a un checkpoint prima del turno che ha attivato il blocco, premi Esc due volte o esegui /rewind. Vedi Checkpointing

Errori della riga di comando

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

Conflitto tra --bg e --print

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

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

Cosa fare:

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

Couldn't tell whether --bg is a flag or text

Hai eseguito claude con --bg o --background in una posizione in cui Claude Code non riusciva a capire se lo intendevi come flag per il background o come testo. Il comando non ha avviato nulla, ha stampato questa riga ed è uscito con codice 1:

Couldn't tell whether --bg is a flag or text here, so nothing was started. To start a background session put it first: claude --bg <prompt>

Se hai digitato --background, la riga nomina invece --background.

Cosa fare:

• Per avviare una sessione in background, esegui di nuovo il comando nella tua shell mettendo il flag per primo: claude --bg --name nightly-audit "<task>"

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

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

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

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

Cosa fare:

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

Invalid --agents configuration

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

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

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

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

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

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

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

Cosa fare:

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

Cloud sessions cannot be created from a --restricted session

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

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

Cosa fare:

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

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

Cloud sessions are disabled by your organization's policy

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

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

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

Se il messaggio invece nomina una credenziale usata da questa sessione e termina con Cloud sessions use your claude.ai login., consulta Cloud sessions use your claude.ai login. Se Claude Code non è riuscito affatto a caricare la policy della tua organizzazione, vedi invece un messaggio diverso.

Cosa fare:

• Chiedi a un Owner della tua organizzazione di abilitare le sessioni cloud nelle impostazioni di amministrazione di Claude Code all'indirizzo claude.ai/admin-settings/claude-code

Cloud sessions use your claude.ai login

Quando il rifiuto della policy nomina una credenziale usata da questa sessione e termina con questa frase, Claude Code ha controllato la policy sulle sessioni cloud dell'organizzazione che ha emesso quella credenziale. Quell'organizzazione può essere diversa da quella a cui appartiene il tuo accesso a claude.ai:

Cloud sessions are disabled by your organization's policy. This session is using ANTHROPIC_API_KEY, so Claude Code checked the policy for the organization that key belongs to. Cloud sessions use your claude.ai login.

L'ultima frase significa che le sessioni cloud vengono eseguite con il tuo accesso a claude.ai anziché con quella credenziale. Questa forma compare quando avvii, riprendi o invii un messaggio a una sessione cloud dalla tua shell, ad esempio con --cloud o --teleport. Prima della v2.1.296, anche in questo caso Claude Code stampava la forma che ti dice di contattare l'amministratore della tua organizzazione.

Couldn't verify your organization's policy for cloud sessions

Questi messaggi indicano che Claude Code non è riuscito a caricare la policy della tua organizzazione, che controlla prima di creare, riprendere o inviare un messaggio a una sessione cloud. Finché la richiesta della policy non è terminata, il messaggio è:

Couldn't verify your organization's policy for cloud sessions. Check your network connection and try again.

All'interno di una sessione, anche un comando che richiede le sessioni cloud, come /teleport o /web-setup, restituisce questo messaggio. Lo fa anche nei casi in cui la tua shell stamperebbe una forma Cloud sessions aren't available:, e la sua seconda frase recita Check your network connection, then restart Claude Code and try again.

Una volta che la richiesta della policy è fallita, il messaggio indica cosa è fallito. Questo vale quando avvii, riprendi o invii un messaggio a una sessione cloud dalla tua shell con un flag come --cloud o --teleport. Senza alcun percorso verso l'API, recita:

Cloud sessions aren't available: couldn't reach api.anthropic.com to load your organization's policy. Check your network or proxy.

Altri errori seguono la stessa apertura con la loro causa specifica, ad esempio un proxy che ha rifiutato la richiesta con HTTP 403, un errore del server o credenziali che l'API non ha accettato. Quando l'API non ha accettato una credenziale che questa sessione usa al posto del tuo accesso a claude.ai, come una variabile d'ambiente ANTHROPIC_API_KEY, il messaggio può anche nominarla e dirti di rimuoverla:

Cloud sessions aren't available: api.anthropic.com didn't accept this session's credentials when Claude Code asked for your organization's policy. Cloud sessions use your claude.ai login. ANTHROPIC_API_KEY is set, so this session is using API-key auth — unset it (or run in a shell without it) to use cloud sessions.

Prima della v2.1.296, anche questi errori stampavano il messaggio Couldn't verify.

Cosa fare:

• Per il messaggio Couldn't verify, controlla la tua connessione di rete e riprova. All'interno di una sessione, riavvia prima Claude Code
• Per un messaggio Cloud sessions aren't available:, fai ciò che richiede la sua causa, ad esempio controllare il tuo proxy o rimuovere la credenziale indicata, quindi esegui di nuovo il comando

Nulla è stato messo in stash perché una cartella ha sostituito un file tracciato

Questo messaggio indica che una cartella nel tuo checkout si trova ora dove prima c'era un file o un link tracciato da git. Compare dopo che scegli l'opzione di stash mentre porti una sessione cloud nel tuo terminale, ad esempio con claude --teleport o /teleport. Mettere in stash quello stato potrebbe eliminare i file all'interno della cartella, quindi Claude Code rifiuta lo stash e lascia invariati il checkout e l'indice:

Error: Nothing was stashed: "f" is now a folder in place of a tracked file or link, and stashing could delete what's in it for good. Commit the change or move the folder somewhere else, then try again.

Cosa fare:

• Esegui il commit della modifica o sposta la cartella altrove, come indica il messaggio, quindi esegui di nuovo il teleport

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

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

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

Il testo dopo i secondi due punti è la diagnostica del validatore e nomina la parola chiave o la posizione che non ha superato il controllo. Gli schemi che usano 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 un JSON valido che non è un oggetto con Error: --json-schema must be a JSON object.

Cosa fare:

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

Settings file exceeds the 2MiB limit

Il file che hai 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 alcun controllo sulle dimensioni, e un file di diversi 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 allo stesso modo un percorso --settings che non è un file regolare: un dispositivo, una FIFO o un socket riporta Error: Cannot use settings file (Not a regular file (device, FIFO, or socket)) seguito dal percorso, e una directory riporta un motivo EISDIR.

Cosa fare:

• Fai puntare --settings a un normale file di impostazioni JSON inferiore a 2 MiB. Consulta Impostazioni per il formato.

Configuration error in ~/.claude.json

Claude Code non è riuscito ad analizzare ~/.claude.json, il file che contiene i dettagli del tuo account, i server MCP e lo stato di ogni progetto. Un avvio non interattivo come claude -p esce con codice 1.

Quando Claude Code trova un backup, l'output lo indica e stampa una riga cp che lo ricopia al suo posto:

Claude configuration file at /home/user/.claude.json is corrupted: <JSON parser's message>
The corrupted file has been backed up to: /home/user/.claude/backups/.claude.json.corrupted.1793664000000
A backup file exists at: /home/user/.claude/backups/.claude.json.backup.1793660400000
You can manually restore it by running: cp -f "/home/user/.claude/backups/.claude.json.backup.1793660400000" "/home/user/.claude.json"

Configuration error in /home/user/.claude.json: <JSON parser's message>

Cosa fare:

• L'output contiene una riga cp: esegui quella riga nel terminale. Su Windows, eseguila in PowerShell.
• L'output non contiene una riga cp, oppure l'errore si ripresenta dopo averla eseguita: se ~/.claude.json contiene ancora la tua configurazione, correggi il suo JSON. Se non ci riesci, copia sopra di esso un altro file .claude.json.backup.<timestamp> da ~/.claude/backups/, se ce n'è uno, oppure rinominalo. Senza alcun file in ~/.claude.json, Claude Code si avvia con le impostazioni predefinite e senza nulla di ciò che il file conteneva.
• ~/.claude.json non contiene più la tua configurazione: trova un file .claude.json.corrupted.<timestamp> che la contenga ancora, in ~/.claude/backups/ o nella tua directory home. Correggi il suo JSON, poi copialo sopra ~/.claude.json. Se non riesci a trovarne o correggerne uno, prova gli stessi passaggi con un file .claude.json.backup.<timestamp> che contenga la tua configurazione. Se nessuno la contiene, rinomina ~/.claude.json e aggiungi di nuovo i tuoi server MCP con claude mcp add.

Claude configuration file was empty and no backup holds anything

Questo messaggio all'avvio indica che il file che nomina era vuoto e che nessuna delle copie .backup del file contiene qualcosa. Claude Code si è avviato con i valori predefiniti per ciò che quel file contiene. I tuoi file settings.json e .mcp.json sono file separati.

Claude configuration file at /home/user/.claude.json was empty and no backup holds anything: starting with defaults.

Cosa fare:

• Configura di nuovo ciò che avevi impostato in quel file. Ad esempio, aggiungi i tuoi server MCP con ambito user e local usando claude mcp add dal terminale.
• Accedi di nuovo se Claude Code te lo chiede

Prima della v2.1.318, Claude Code segnalava un file vuoto senza backup come danneggiato.

The current directory no longer exists

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

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

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

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

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

Cosa fare:

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

Directory temporanea rifiutata o impossibile da creare

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

Claude Code's temporary directory /tmp/claude-501 could not be created: the volume holding /tmp is full (ENOSPC). Free space on that volume, or set CLAUDE_CODE_TMPDIR to a directory on another one, then try again.

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 could not be created seguito da is full (ENOSPC), libera spazio su disco nel volume indicato dal messaggio. Quando invece dice your disk quota on the volume holding /tmp is used up (EDQUOT), elimina i tuoi file su quel volume che non ti servono più
• Per le forme Refusing to use it, rimuovi la voce indicata stessa, non ciò a cui punta un link, e avvia di nuovo Claude Code; per la forma owned by uid, solo un amministratore o quell'utente può rimuoverla
• Per is not readable, esegui chmod 0700 sulla directory indicata, oppure rimuovila e avvia di nuovo
• In tutti questi casi, imposta CLAUDE_CODE_TMPDIR su una directory che controlli e avvia di nuovo Claude Code, lasciando intatto il percorso rifiutato

Prima della v2.1.309, Claude Code stampava solo il testo di errore del sistema operativo quando il volume era pieno o la tua quota era esaurita. Un esempio è ENOSPC: no space left on device, mkdir '/tmp/claude-501', e si applicano gli stessi passaggi.

Claude Code non è riuscito a salvare perché il disco è pieno

Questa riga su stderr dopo un'esecuzione di claude -p indica che il disco è pieno o che la tua quota disco è esaurita, quindi Claude Code non è riuscito a salvare tutto ciò che riguarda l'esecuzione:

Error: Claude Code could not save all of this session's transcript under /Users/you/.claude because the disk is full (ENOSPC). If you resume this session, part of the conversation may be missing. Free up space on that disk before the next run.

Con output di testo o json, l'esecuzione esce con codice 1 e la risposta è già stata stampata. Con output stream-json, l'esecuzione mantiene il suo consueto codice di uscita e la risposta arriva comunque.

Cosa fare:

• the disk is full (ENOSPC): prima della prossima esecuzione, libera spazio sul disco che contiene il percorso indicato nel messaggio
• your disk quota is used up (EDQUOT): prima della prossima esecuzione, libera spazio o richiedi una quota maggiore

Directory couldn't be resolved to a real location

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

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

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

Cosa fare:

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

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

Workspace not trusted when starting Remote Control

[!NOTE]

Se claude ultrareview ha stampato Error: Workspace not trusted, consulta invece Workspace not trusted when running claude ultrareview.

Hai avviato la modalità server di Remote Control con claude remote-control o il suo alias claude rc in una directory che non hai considerato attendibile, e il comando non ha potuto chiederti se considerarla attendibile. Ad esempio, lo standard input o lo standard output del comando non è un terminale perché uno dei due è reindirizzato o collegato tramite pipe. Il comando 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 anch'esse con Error: Workspace not trusted. compaiono in un terminale troppo piccolo per mostrare cosa attiva la fiducia nella directory, o in uno che non ha riportato le sue dimensioni. Ingrandisci la finestra o passa a una normale finestra di terminale, quindi esegui di nuovo claude rc.

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

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

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

Cosa fare:

• Considera prima attendibile la directory da un terminale: esegui lì claude rc e rispondi y, oppure esegui lì claude e accetta la finestra di dialogo di fiducia nel workspace, quindi esegui di nuovo il comando originale
• Nella tua directory home, spostati in una directory di progetto e avvia Remote Control da lì

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

Workspace not trusted when running claude ultrareview

In una cartella che non hai considerato attendibile, quando claude ultrareview non può chiederti se la consideri attendibile, l'esecuzione esce con codice 1 prima che la revisione inizi:

Error: Workspace not trusted. Please run `claude` in /Users/you/project first to review and accept the workspace trust dialog. Or, in a script or CI job, pass `--trust-workspace` to trust the folder for this run only.

Ad esempio, il sottocomando non può chiedere quando il suo standard input o standard output non è un terminale. Inviare l'output a un file, come in claude ultrareview --json > findings.json, significa che lo standard output non è un terminale.

Cosa fare:

• In uno script o in un job di CI, aggiungi --trust-workspace per considerare attendibile la cartella per quell'esecuzione: claude ultrareview --trust-workspace. Aggiungilo solo per codice di cui ti fidi, perché git e Claude Code possono quindi eseguire programmi indicati nella configurazione git e nelle impostazioni di progetto della cartella. Per una pull request il cui codice non è attendibile, esegui la revisione da un branch di cui ti fidi.
• Sulla tua macchina, esegui claude in quella cartella e accetta la finestra di dialogo di fiducia nel workspace, quindi esegui di nuovo il comando originale

Ciascuno di questi messaggi di claude ultrareview indica che nessuna revisione è stata avviata e che il codice di uscita è 1:

• Error: Workspace not trusted. This terminal ...: il terminale non ha riportato il numero di righe e colonne, oppure non riesce a contenere la domanda di fiducia e i relativi avvisi. Ingrandiscilo o usa un terminale che riporti le sue dimensioni, quindi esegui di nuovo claude ultrareview. Al di fuori della tua directory home, puoi anche eseguire claude in quella cartella una volta e accettare la finestra di dialogo di fiducia, così le esecuzioni successive lì non chiederanno nulla.
• Error: Workspace not trusted. <folder> is your home directory: poiché la fiducia per la tua directory home non viene mai salvata, eseguire prima claude lì non può aiutare. Esegui invece claude ultrareview da una directory di progetto, dopo aver eseguito claude lì una volta per accettare la finestra di dialogo di fiducia, oppure aggiungi --trust-workspace.
• No answer in time. seguito da Error: Workspace not trusted: la domanda Trust <folder>? [y/N] è rimasta senza risposta per 5 minuti. Esegui di nuovo claude ultrareview e rispondi.
• Ultrareview did not start: <folder> is not trusted: hai rifiutato alla domanda Trust <folder>? [y/N], ad esempio rispondendo n o premendo Enter. Per avviare la revisione, esegui di nuovo claude ultrareview e rispondi y.
• Ultrareview did not start: `--trust-workspace` takes no value: dopo --trust-workspace segue qualcosa che non è un flag, come un numero di PR o false. Se non ti fidi della cartella, ometti il flag. Per considerarla attendibile per questa esecuzione, metti il numero di PR o il branch di base prima del flag: claude ultrareview 1234 --trust-workspace.

Prima della v2.1.309, claude ultrareview non accettava --trust-workspace.

Remote Control non si è avviato perché una domanda non ha ricevuto risposta

Questo messaggio indica che claude remote-control ha posto la domanda di primo avvio citata nel messaggio e non ha ricevuto risposta:

Remote Control did not start: "Enable Remote Control?" got no answer. Run `claude remote-control` at a terminal and answer y once; it won't ask again.
Remote Control did not start: "Choose [1/2] (default: 1):" got no answer. You can run `claude remote-control` and choose, or pass --spawn=same-dir or --spawn=worktree.

Cosa fare:

• Enable Remote Control?: in uno script o in un servizio, lo standard input termina prima che qualcuno possa rispondere. Esegui claude remote-control una volta in un terminale, con lo stesso utente con cui viene eseguito il tuo script o servizio, e rispondi y.
• Choose [1/2] (default: 1):: esegui di nuovo claude remote-control e scegli una modalità di spawn, oppure passa --spawn=same-dir o --spawn=worktree per saltare la domanda

Not carried over to the sessions Remote Control starts

Hai avviato Remote Control con un flag globale di claude prima del verbo remote-control, uno che limiterebbe o configurerebbe le sessioni avviate da Remote Control, come --settings, --setting-sources, --permission-mode, --disallowed-tools o --mcp-config. Un flag posto prima del verbo non raggiunge mai quelle sessioni. Claude Code si rifiuta invece di avviarsi, 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 si possono scartare senza conseguenze, come --verbose, --model, o un --session-id o --plugin-dir inserito da un wrapper: li ignora e Remote Control si avvia.

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

Cosa fare:

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

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

--sandbox or --no-sandbox is not supported by claude remote-control

Questo errore indica che il comando che avvia il tuo server Remote Control passa --sandbox o --no-sandbox dopo remote-control, e claude remote-control non accetta nessuno dei due flag. Il server esce con codice 1 invece di avviarsi:

Error: --sandbox is not supported by claude remote-control. The flag had no effect and was removed. To sandbox sessions, set sandbox.enabled to true in settings.
Error: --no-sandbox is not supported by claude remote-control. The flag had no effect and was removed. Remove it from the command.

Cosa fare:

• Rimuovi il flag dal comando, anche in uno script o in una definizione di servizio che avvia il server per te, quindi eseguilo di nuovo
• Per eseguire in sandbox le sessioni avviate dal server, attiva il sandboxing impostando sandbox.enabled su true in un file di impostazioni

Entrambi i flag sono stati rimossi da claude remote-control nella v2.1.300, quindi un comando scritto per una versione precedente può ancora contenerne uno.

claude import is not yet available in this build

Hai 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 tramite un feature flag che recupera da Anthropic e memorizza nella cache su disco. Questo messaggio indica che il valore nella cache è disattivato. La causa è di solito una delle seguenti:

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

Cosa fare:

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

Could not read Claude Code config

Hai eseguito claude import mentre Claude Code non riusciva ad analizzare ~/.claude.json, il file in cui memorizza i dettagli del tuo account e lo stato per progetto. Il sottocomando legge quel file per verificare la disponibilità ma non mostra la finestra di dialogo di ripristino mostrata dalla sessione interattiva, 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 ripristino gestiva il file.

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

Cosa fare:

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

Could not import a server from Claude Desktop

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

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

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

Cosa fare:

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

Cannot add MCP server to the managed scope

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

Cannot add MCP server to scope: managed

Cosa fare:

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

Cannot add MCP server when managed settings allow only plugin servers

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

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

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

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

Cosa fare:

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

Can't read .mcp.json

Un comando che legge il .mcp.json del progetto, come claude mcp add o claude mcp add-json con --scope project, oppure claude mcp remove, ha rilevato che il file nella directory corrente non è un file regolare o è più grande di 2 MiB, quindi 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, una FIFO in .mcp.json lasciava il comando in attesa indefinitamente senza alcun output, e un collegamento simbolico a un file di dispositivo come /dev/zero faceva crescere la memoria finché il processo non veniva terminato.

Cosa fare:

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

MCP server was not saved or removed

Questo errore significa che un comando come claude mcp add o claude mcp remove non è riuscito a scrivere la tua modifica in ~/.claude.json. Altri processi di Claude Code potrebbero aver mantenuto il file bloccato, oppure il file potrebbe essere di sola lettura o protetto da una sandbox.

MCP server "example" was not saved to /home/user/.claude.json. If other Claude Code processes use that file, they may have kept it locked: add the server again, with CLAUDE_CODE_CONFIG_LOCK_WAIT_MS=60000 set to wait up to a minute. If that file is read-only or protected by a sandbox, make it writable or run the command outside the sandbox first.

Dopo una rimozione, il messaggio riporta was not removed from al posto di was not saved to, e remove the server again al posto di add the server again. Per un server di ambito local, il percorso è seguito dalla directory di progetto a cui appartiene la voce, come (local scope for /path/to/project).

Cosa fare:

• Sono in esecuzione altri processi di Claude Code: il comando attende circa 10-20 secondi il blocco sul file, poi rinuncia senza scrivere. Esegui di nuovo lo stesso comando con CLAUDE_CODE_CONFIG_LOCK_WAIT_MS impostata su un'attesa più lunga in millisecondi, ad esempio 60000.
• Il file è di sola lettura o protetto da sandbox: rendi scrivibile il file indicato dal messaggio ed esegui di nuovo lo stesso comando di aggiunta o rimozione, oppure esegui quel comando al di fuori della sandbox.

Prima della v2.1.283, claude mcp add, claude mcp add-json e claude mcp remove segnalavano il successo anche quando la modifica non raggiungeva il file. Prima della v2.1.318, il messaggio non menzionava il blocco e Claude Code non leggeva CLAUDE_CODE_CONFIG_LOCK_WAIT_MS.

MCP server may not have been saved or removed

Hai eseguito claude mcp add, claude mcp add-json o claude mcp remove per un server nell'ambito user o local, e Claude Code non è riuscito a rileggere ~/.claude.json per confermare la modifica. La modifica potrebbe essere o non essere su disco. Le parentesi dopo to confirm the change indicano il motivo.

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

Dopo una rimozione, il messaggio riporta may not have been removed e termina con then remove the server again if it is still listed. Se il motivo è the file was not found, il server potrebbe essere ancora configurato.

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

Cosa fare:

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

Server is Anthropic-hosted and doesn't support local OAuth

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

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

Cosa fare:

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

Server rejected the Authorization header minted by the configured headersHelper

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

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

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

Cosa fare:

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

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

MCP server rejected the elicitation capability

Un server MCP basato su Java MCP SDK dalla 0.11.0 alla 0.17.0 ha rifiutato la connessione. Queste versioni dell'SDK non riescono ad analizzare le modalità di elicitation form e url che Claude Code dichiara nel suo handshake. Il messaggio recita:

This server (Java MCP SDK 0.17.0 or older) rejected Claude Code's elicitation capability. Set "bareElicitationCapability": true for it, or upgrade to Java MCP SDK 0.17.1+ (Spring AI 1.0.7+ or 1.1.6+).

Cosa fare:

• Aggiorna il server a Java MCP SDK 0.17.1 o successivo, oppure a una delle release di Spring AI indicate nel messaggio
• Oppure aggiungi "bareElicitationCapability": true alla voce di quel server nella tua configurazione MCP, quindi riavvia Claude Code. Il campo è accettato nelle voci stdio, sse, http e ws e richiede Claude Code v2.1.281 o versioni successive

Questa voce di .mcp.json imposta il campo per un server HTTP:

{
  "mcpServers": {
    "inventory": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "bareElicitationCapability": true
    }
  }
}

Dopo il riavvio, /mcp mostra il server come connesso. Claude Code dichiara la modalità form solo a quel server, quindi rimuovi il campo una volta che lo hai aggiornato.

Un server può anche fallire con un proprio testo di errore, ad esempio uno che contiene Unrecognized field "form". Si applicano le stesse soluzioni.

MCP permission prompt tool not found

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

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

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

Cosa fare:

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

OAuth callback port is already in use

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

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

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

Cosa fare:

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

No available ports for OAuth redirect

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

No available ports for OAuth redirect

Prima della v2.1.268, Claude Code non ripiegava su una porta assegnata dal sistema operativo, quindi il messaggio compariva anche quando solo le porte scelte da esso non potevano essere associate. Questo può accadere sugli host Windows in cui Hyper-V riserva intervalli di porte che coprono le porte tra cui sceglie Claude Code.

Cosa fare:

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

/security-review non riesce senza origin/HEAD

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

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

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

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

Claude Code mostra lo stesso errore per qualsiasi skill che inserisce contesto dinamico, e un comando inserito che fallisce interrompe l'invocazione di quella skill.

Stringhe analoghe compaiono prima ancora che il comando venga eseguito:

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

Cosa fare:

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

No shell command in a skill or command was run

No shell command in <name> was run indica che un comando di contesto dinamico !`<command>` in quel file di skill o di comando contiene un carattere che lo strumento Bash o PowerShell rifiuta:

• Entrambi gli strumenti: un carattere di controllo grezzo diverso da una tabulazione o da un a capo
• Strumento PowerShell: anche U+FEFF o U+180E

Il messaggio termina con il comando rifiutato, mostrando ogni carattere rifiutato come �, come in questo esempio dello strumento Bash:

No shell command in /my-skill was run, because the Bash tool does not accept one of them: command contains control characters that would be hidden in the approval dialog. Unprintable characters are shown as � below: remove them from the skill or command file, or from the arguments or options substituted into it.
build.sh --target�dist

Cosa fare:

• Trova ogni � nel comando citato alla fine del messaggio. Rimuovi il carattere che rappresenta dal file di skill o di comando, oppure dagli argomenti o dalle opzioni sostituiti nel file.

Input must be provided when using --print

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

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

Cosa fare:

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

Claude Code can't read the keyboard here

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

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

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

Su Windows il messaggio recita:

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

Cosa fare:

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

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

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

Input contained only whitespace

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

• Argomento del prompt o stdin tramite pipe per claude -p: claude 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 all'API il messaggio composto solo da spazi, che rifiutava la richiesta con un errore 400.

Cosa fare:

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

stream-json input carried over 256M characters with no newline

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

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

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

Cosa fare:

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

Unknown command

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

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

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

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

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

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

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

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

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

Cosa fare:

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

Diff is too large for ultrareview

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

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

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

Cosa fare:

• Passa un branch di base più vicino al tuo lavoro, ad esempio /code-review ultra develop, in modo che la revisione copra solo il diff rispetto a quel branch
• Suddividi la modifica in branch più piccoli e revisiona ciascuno di essi. I file indicati nel messaggio contribuiscono con il maggior numero di righe modificate, quindi inizia spostandoli in un branch dedicato.

Could not find merge-base with the base branch

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

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

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

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

Cosa fare:

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

Your checkout has no branches

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

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

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

Cosa fare:

• Crea un branch al commit corrente con git checkout -b <name>, poi ripeti la revisione

No GitHub account is connected to your Claude account

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

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

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

Cosa fare:

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

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

Your connected GitHub account can't see the repository

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

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

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

Cosa fare:

• Se la tua CLI gh locale può leggere il repository, esegui /web-setup per collegare quel login al tuo account Claude
• Ripeti la revisione dopo la modifica

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

The GitHub App preflight failed transiently

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

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

Cosa fare:

• Esegui di nuovo il comando dopo qualche istante. Quando il controllo GitHub ha esito positivo, Claude Code può avviare la sessione da un clone GitHub, quindi il caricamento fallito non blocca più l'avvio
• Se i nuovi tentativi continuano a fallire, l'inizio del messaggio indica cosa ha bloccato il caricamento. Quando si tratta di una causa che puoi risolvere, risolvila in modo che la sessione possa invece avviarsi dal tuo repository locale

Prima della v2.1.251, Claude Code terminava il messaggio con Please set up GitHub on https://claude.ai/code anche quando il controllo GitHub falliva solo temporaneamente, e un consiglio di configurazione non può risolvere un errore temporaneo.

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

Hai avviato una sessione cloud che carica il tuo repository locale, oppure una ultrareview di un branch, e il caricamento non può seguire una delle impostazioni git che determinano quali regole di attributo si applicano ai tuoi file. Se il caricamento procedesse ignorando una regola, un file che git trasforma prima di memorizzarlo, ad esempio uno che un clean filter cifra, potrebbe arrivare nel cloud così com'è sul disco. Claude Code rifiuta invece il caricamento, 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 indica l'impostazione e dove è definita, e termina con la correzione per il caso riscontrato. Lo stesso rifiuto compare per core.attributesFile e attr.tree, ciascuno con la propria correzione.

Il messaggio può indicare un file di configurazione che la tua configurazione git include tramite una direttiva include o includeIf, anche quando la condizione di quella direttiva non si applica a questo repository.

Cosa fare:

• Applica la correzione indicata nell'ultima frase del messaggio

GitHub isn't connected to your Claude account

Hai avviato una sessione cloud dal tuo repository locale, ad esempio con /autofix-pr. Nessun account GitHub è collegato al tuo account Claude, oppure il collegamento è scaduto, quindi Claude Code rifiuta l'avvio:

GitHub isn't connected to your Claude account, so this repository can't be cloned in the cloud. Run /web-setup to connect with your GitHub CLI login, or connect on the web at https://claude.ai/connect-github

Quando crei un'attività pianificata nel cloud con /schedule, lo stesso messaggio compare come nota di configurazione che indica il repository; la nota non impedisce la creazione dell'attività.

Cosa fare:

• Esegui /web-setup per collegare il tuo login della GitHub CLI al tuo account Claude, oppure collega un account su claude.ai/connect-github. Consulta Opzioni di autenticazione GitHub per capire in cosa differiscono le due opzioni.
• Esegui di nuovo il comando un minuto dopo il collegamento

Prima della v2.1.268, Claude Code segnalava questa situazione come un errore temporaneo del controllo della Claude GitHub App e suggeriva di riprovare o di installare l'app; nessuna delle due azioni collega un account GitHub.

Una policy dell'organizzazione GitHub sta bloccando Claude

Hai eseguito al prompt di Claude Code un comando che avvia una sessione cloud, come /autofix-pr. Prima di creare la sessione, Claude Code verifica l'accesso di Claude al repository su GitHub, e GitHub l'ha rifiutato perché la tua organizzazione GitHub ha una policy che blocca Claude. Claude Code si ferma lì e mostra un messaggio che indica la policy.

Quando a bloccare l'accesso è un'allowlist di IP, il messaggio è:

Your GitHub organization has an IP allowlist that is blocking Claude. Add Claude's IP ranges to your GitHub allowlist.

Quando a bloccarlo è il single sign-on, il messaggio è:

Your GitHub organization requires single sign-on. Disconnect and reconnect GitHub on the Connectors page in Claude on the web, click Authorize next to your organization when GitHub asks, then try again.

Quando a bloccarlo è una policy di accesso condizionale di Microsoft Entra ID, il messaggio è:

Your GitHub organization's identity provider (Microsoft Entra ID) has a Conditional Access policy that is blocking Claude. Ask your GitHub Enterprise or Entra ID admin to allow Claude in that policy.

Cosa fare:

• Allowlist di IP: chiedi a un owner della tua organizzazione o enterprise GitHub di consentire gli indirizzi IP in uscita di Anthropic. Consulta Allowlist e firewall di GitHub per gli indirizzi e le impostazioni GitHub da modificare.
• Single sign-on: scollega GitHub su claude.ai/customize/connectors, poi collegalo di nuovo. Quando GitHub lo chiede, fai clic su Authorize accanto alla tua organizzazione in modo che il nuovo collegamento sia autorizzato per il suo single sign-on.
• Policy di accesso condizionale: chiedi al tuo amministratore di GitHub Enterprise o di Microsoft Entra ID di consentire Claude in quella policy
• Dopo la modifica, esegui di nuovo il comando

Single sign-on authorization needed

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

Single sign-on authorization needed
<owner>/<repo> belongs to an organization that enforces SAML single sign-on, and your GitHub CLI token isn't authorized for it yet.

Cosa fare:

• Autorizza di nuovo il tuo login della GitHub CLI con gli scope repo e workflow eseguendo gh auth refresh -h github.com -s repo,workflow, e autorizza l'organizzazione quando GitHub richiede il single sign-on
• Se ti autentichi con un personal access token in GH_TOKEN, apri github.com/settings/tokens, seleziona Configure SSO sul token e autorizza l'organizzazione
• Esegui di nuovo /install-github-app

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

Failed to resume the conversation

Claude Code non è riuscito a leggere o elaborare la trascrizione salvata della sessione selezionata dal selettore di claude --resume, quindi termina il processo anziché proseguire in uno stato caricato solo in parte. Il messaggio include il comando per riprovare:

Failed to resume the conversation.
Run claude --resume <session-id> to retry, or claude to start a new session.

Claude Code esce con codice 1 dopo aver mostrato il messaggio. Il selettore di /resume all'interno di una sessione in esecuzione riporta invece Failed to resume conversation nella conversazione, e la tua sessione corrente continua a funzionare. Prima della v2.1.216, una ripresa non riuscita dal selettore di claude --resume restava indefinitamente sull'indicatore Resuming conversation… invece di mostrare questo messaggio.

Cosa fare:

• Esegui claude --resume <session-id> con l'ID di sessione indicato nel messaggio per riprovare
• In una versione precedente alla v2.1.285, se il nuovo tentativo fallisce allo stesso modo, esegui claude update e riprendi di nuovo. Quelle versioni falliscono la ripresa quando la trascrizione salvata contiene una voce che non riescono a leggere.
• Se il nuovo tentativo fallisce ancora, esegui claude per avviare una nuova sessione

No conversation found with the session ID

Hai passato un ID di sessione a claude --resume <session-id> e nessuna trascrizione salvata corrisponde:

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

Claude Code esce con codice 1 dopo aver mostrato il messaggio. Claude Code cerca l'ID prima nel progetto corrente, poi in tutti gli altri progetti su questa macchina. Prima della v2.1.223, la ricerca si fermava alla directory del progetto corrente e ai suoi worktree git, quindi riprendi dalla directory in cui la sessione ha lavorato per ultima.

Cause comuni:

• ID digitato in modo errato: per un'esecuzione non interattiva, l'ID è il campo session_id dell'output di --output-format json
• Trascrizione eliminata: Claude Code rimuove le trascrizioni dopo il periodo di conservazione, 30 giorni per impostazione predefinita, secondo le regole di pulizia per la conservazione
• Macchina diversa: Claude Code memorizza le trascrizioni in locale, quindi riprendi la sessione sulla macchina in cui è stata eseguita
• Copie duplicate: se hai copiato una directory di progetto sotto ~/.claude/projects così che due trascrizioni riportano lo stesso ID, Claude Code mostra questo messaggio anziché riprendere arbitrariamente una delle copie

Cosa fare:

• Per una sessione interattiva, apri il selettore delle sessioni con claude --resume e premi Ctrl+A per estenderlo a tutti i progetti su questa macchina, poi seleziona la sessione
• Le sessioni create con claude -p o con l'Agent SDK non compaiono nel selettore, quindi ricontrolla l'ID confrontandolo con il session_id stampato dall'esecuzione originale

Windows reported an error (EBADF) when Claude Code read this session's transcript file

Hai ripreso una sessione su Windows, il suo file di trascrizione salvato si è aperto normalmente, e la lettura è poi fallita con l'errore di sistema EBADF. L'errore di sistema non spiega perché la lettura è fallita, quindi il messaggio suggerisce le cause probabili e cosa provare:

Windows reported an error (EBADF) when Claude Code read this session's transcript file, although the file had opened normally. This can happen when other software intercepts file reads — security, encryption or endpoint-management tools, for example. If it keeps happening for this conversation, try excluding the folder that holds Claude Code's session transcripts from such software (the .claude folder in your user profile, unless the app or CLAUDE_CONFIG_DIR points Claude Code elsewhere), or adding Claude Code to its allowed applications, then resume again.

Il messaggio segue la riga di errore del comando stesso, ad esempio Failed to resume session <session-id>. Un comando claude --resume o claude -p esce con codice 1 dopo averlo mostrato. Dopo /resume all'interno di una sessione, la tua sessione corrente continua a funzionare.

Cosa fare:

• Escludi la cartella che contiene le trascrizioni delle tue sessioni dai software che analizzano o intercettano le letture dei file, come strumenti di sicurezza, cifratura o gestione degli endpoint. Le trascrizioni si trovano in %USERPROFILE%\.claude\projects per impostazione predefinita, oppure nella directory indicata da CLAUDE_CONFIG_DIR
• Se non puoi aggiungere un'esclusione, aggiungi invece Claude Code alle applicazioni consentite di quel software
• Riprendi di nuovo la sessione

Prima della v2.1.282, l'errore non era accompagnato da alcuna spiegazione: claude --resume <session-id> terminava con Failed to resume session <session-id>, e un'esecuzione con -p stampava solo il testo dell'errore di sistema, ad esempio Failed to resume session: EBADF: bad file descriptor, read.

Cannot switch renderers in this session

Quando cambi renderer, Claude Code riavvia il proprio processo. Hai eseguito /tui in una sessione che Claude Code rifiuta di riavviare, quindi non effettua il cambio e non salva nulla. Il messaggio che vedi ti indica la causa:

• Cannot switch renderers while work is running in the background: hai attività in background in esecuzione che un riavvio abbandonerebbe, come una shell in background o un subagent. Attendi che l'attività termini o interrompila con /tasks, poi esegui di nuovo /tui fullscreen o /tui default
• Cannot switch renderers in this session: la sessione ha restrizioni che Claude Code non può trasmettere al processo riavviato. Prima della v2.1.234, Claude Code effettuava comunque il riavvio e la sessione rilanciata veniva eseguita senza di esse

Nel messaggio sulle restrizioni, la parte tra parentesi indica le restrizioni rilevate da Claude Code:

Cannot switch renderers in this session — it has restrictions a restart can't carry over (permission rules set for this session only). Nothing was changed. Running /tui fullscreen in a session started without them switches every later session too.

Ogni motivo che il messaggio può mostrare tra parentesi:

• launch flags: a custom system prompt, a tool allowlist, or restricted settings: hai avviato la sessione con un flag che Claude Code non ritrasmette 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 dei permessi da un hook o da un chiamante SDK ha aggiunto regole deny o ask con destinazione session. Le regole allow limitate alla sessione non provocano il rifiuto. Un riavvio le elimina, e Claude Code invece chiede di nuovo
• ask-before-running rules with no command-line form: un aggiornamento dei permessi da un hook o da un chiamante SDK ha aggiunto regole ask insieme alle regole che Claude Code ritrasmette come --allowed-tools e --disallowed-tools. Non esiste alcun flag per le regole ask
• permission rules a command line cannot carry intact e added directories a command line cannot carry intact: un aggiornamento dei permessi ha aggiunto una regola o un percorso di directory durante la sessione. La riga di comando del processo riavviato non può trasmetterne il testo come lo stesso valore

Cosa fare:

• In una sessione avviata senza quelle restrizioni, esegui /tui fullscreen, oppure /tui default per tornare indietro. Claude Code salva lì l'impostazione tui

Can't restart while work is running or Remote Control is connected

Claude Code non si è riavviato, e la tua sessione continua a funzionare come prima. Segui la soluzione indicata nel messaggio.

Claude Code couldn't restart

Quando questo messaggio dice che la tua conversazione è salvata, la conversazione è su disco e puoi riprenderla dal punto in cui si è interrotta. Claude Code si stava riavviando, ad esempio per passare al rendering a schermo intero o uscirne dopo che hai eseguito /tui, e non è riuscito ad avviare il nuovo processo, quindi è uscito con stato 1:

Claude Code couldn't restart. Your conversation is saved. Start Claude Code again and run /resume to pick it up.

Quando il riavvio non aveva alcuna conversazione da riaprire, ad esempio perché /tui era il tuo primo input in una nuova sessione, il messaggio è Claude Code couldn't restart. Start Claude Code again.

Cosa fare:

• Esegui di nuovo claude nella tua shell. Se il messaggio diceva che la tua conversazione è salvata, esegui /resume nella nuova sessione e seleziona la conversazione. Se non è nell'elenco, estendi il selettore delle sessioni
• Se i riavvii continuano a fallire, avvia Claude Code dalla tua shell con claude --debug-file claude-debug.log. Se un riavvio da quella sessione fallisce, claude-debug.log nella directory da cui hai avviato registra una riga Failed to relaunch: con l'errore del sistema operativo. Includi quella riga quando segnali il problema

Couldn't open Claude Desktop

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

Il testo tra parentesi indica il comando fallito, con il suo stato di uscita e la prima riga del suo output di errore quando li ha prodotti. Su macOS quel comando è open, come in questo esempio; su Windows è rundll32:

Error: Couldn't open Claude Desktop (`open` exited 1: LSOpenURLsWithRole() failed for the URL claude://resume?session=<session-id> with error -10814). Open Claude Desktop and try again.

Cosa fare:

• Apri tu stesso Claude Desktop, poi esegui di nuovo /desktop o claude --desktop
• Per leggere l'output di errore completo del comando fallito, attiva il logging di debug con /debug ed esegui di nuovo /desktop, oppure esegui claude --desktop --debug-file <path>, poi controlla il log di debug

Prima della v2.1.285, il messaggio terminava con Open Claude Desktop and run /desktop again. Prima della v2.1.275, era Failed to open Claude Desktop. Please try opening it manually. e non diceva cosa fosse fallito.

/terminal-setup ha lasciato invariata la tua keymap di Zed

Hai eseguito /terminal-setup in Zed, e Claude Code non è riuscito a completare l'aggiornamento del tuo keymap.json di Zed, quindi ha lasciato il file così com'era.

Ogni messaggio indica il percorso della tua keymap e termina con il blocco di scorciatoie da tastiera da aggiungere tu stesso:

Couldn't update your Zed keymap, so it was left unchanged.
To add the binding yourself, add this block to the keymap array in <path to keymap.json>:
{ "context": "Terminal", "bindings": { "shift-enter": ["terminal::SendText", "\u001b\r"] } }

La prima riga del messaggio indica la causa:

• Couldn't read your Zed keymap, so it was left unchanged.: Claude Code non è riuscito a leggere il file, ad esempio a causa dei permessi del file
• Your Zed keymap isn't a readable list of keybindings, so it was left unchanged.: il file è stato letto correttamente ma non viene interpretato come un array di blocchi di scorciatoie da tastiera, nemmeno consentendo commenti // e virgole finali
• Couldn't back up your Zed keymap; not modifying it.: Claude Code non è riuscito a copiare il file in un backup .bak accanto a esso, quindi non ha modificato nulla
• Couldn't update your Zed keymap, so it was left unchanged.: il risultato unito non è stato verificato come keymap valida contenente la scorciatoia, quindi Claude Code lo ha scartato invece di scriverlo. Un blocco di scorciatoie da tastiera con una chiave duplicata può causare questo problema

Cosa fare:

• Copia il blocco dal messaggio nell'array di primo livello del tuo keymap.json al percorso indicato nel messaggio
• Per isn't a readable list of keybindings, correggi l'errore di sintassi, oppure rendi un array il valore di primo livello del file, poi esegui di nuovo /terminal-setup

Prima della v2.1.247, /terminal-setup non riusciva a interpretare una keymap di Zed che usava commenti // o virgole finali, e sostituiva l'intero file con la sola propria scorciatoia pur segnalandola come installata. Per ripristinare una keymap sostituita da una versione precedente, usa il file di backup .bak descritto in Inserire prompt su più righe.

Skill usage reports are not available on this connection

Hai eseguito /skill-doctor tramite Remote Control, dal telefono o dal browser. Claude Code non invia il report sull'utilizzo delle skill tramite Remote Control e risponde invece con questo messaggio:

Skill usage reports are not available on this connection.

Cosa fare:

• Esegui /skill-doctor nel terminale della macchina su cui è in esecuzione la sessione, oppure esegui lì claude -p "/skill-doctor"

Custom output styles can't be selected over Remote Control

Hai eseguito /output-style dall'app mobile o dal web tramite Remote Control, oppure il comando è arrivato in un messaggio inoltrato nella sessione. Poiché un turno di questo tipo potrebbe non provenire dal proprietario dell'account, Claude Code elenca e seleziona solo gli stili predefiniti su di esso, e aggiunge questo avviso ogni volta che il comando elenca gli stili o non riconosce il nome che hai fornito. Il nome di uno stile personalizzato riceve la stessa risposta di un nome inesistente:

Custom output styles can't be selected over Remote Control or from a relayed message. Select one in the session itself, or pick a built-in style here.

Cosa fare:

• Scegli uno stile predefinito, ad esempio /output-style concise
• Per usare uno stile personalizzato, imposta outputStyle nel file .claude/settings.local.json del progetto, oppure esegui /output-style <style> nel terminale della sessione stessa, se ne ha uno

Output styles are saved to local settings which this session doesn't load

Hai provato a cambiare stile di output con /output-style <style> o /config outputStyle=<style> in una sessione le cui fonti di impostazioni escludono local. Alcuni esempi sono una sessione dell'Agent SDK il cui settingSources non include "local" e una sessione CLI avviata con un valore di --setting-sources che non include local. Entrambi i comandi salvano lo stile in .claude/settings.local.json, un file che una sessione di questo tipo non rilegge mai, quindi Claude Code rifiuta 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:

• Aggiungi local alle fonti di impostazioni della sessione e cambia di nuovo stile
• Imposta la chiave outputStyle in un file di impostazioni che la sessione carica, come .claude/settings.json nel progetto o ~/.claude/settings.json. Nell'SDK TypeScript, imposta invece outputStyle all'interno dell'oggetto inline settings; consulta Attivare uno stile di output

/recap only runs when you ask for it yourself

La richiesta /recap non proviene dal tuo input. È arrivata in un messaggio inoltrato nella sessione da un thread di Slack, Teams o di un progetto, oppure in un prompt inviato da un'attività pianificata nel cloud o da un altro programma.

Un messaggio inoltrato riceve l'avviso anche se l'hai scritto tu. Claude Code non può stabilire che un messaggio inoltrato o automatizzato provenga dalla persona il cui account esegue la sessione, quindi risponde con questo avviso invece di un riepilogo:

/recap only runs when you ask for it yourself in this session: from the terminal, the Claude app or claude.ai/code, or over Remote Control. A message relayed from Slack, Teams or a project thread, or sent by a routine or another program, can't request it.

Un /recap che passi a claude -p, o che la tua applicazione Agent SDK invia a una sessione da essa avviata, conta come tuo input.

Cosa fare:

• Apri tu stesso la sessione ed esegui lì /recap: nel suo terminale, nell'app Desktop o nell'app mobile, su claude.ai/code, oppure tramite Remote Control
• Se l'ha inviato un'attività pianificata nel cloud o un altro programma, rimuovi /recap da quel prompt

/feedback is disabled by your organization's policy

Questo messaggio indica che il feedback sul prodotto è disattivato, quindi il comando che hai digitato non apre la finestra di dialogo del feedback. Sia una policy dell'organizzazione sia un rifiuto precedente producono il messaggio:

• Policy dell'organizzazione: la policy della tua organizzazione non consente il feedback sul prodotto da Claude Code. /feedback, /bug e /share rispondono tutti con il messaggio.
• Rifiuto precedente: il servizio di feedback ha rifiutato una segnalazione che hai inviato, ad esempio con Couldn't send feedback: Feedback has not been enabled for your organization. /feedback e /bug possono quindi rispondere con il messaggio. Questo dura sette giorni da quel rifiuto su questa macchina. Vale per ogni piano, inclusi Pro e Max.

Il messaggio indica il comando che hai digitato al prompt di Claude Code:

/feedback is disabled by your organization's policy. To report a bug, open an issue at https://github.com/anthropics/claude-code/issues. Issues are public, so leave out anything confidential.

Il messaggio può anche essere costituito dalla sola prima frase.

Cosa fare:

• Per segnalare un bug, apri una issue su github.com/anthropics/claude-code/issues. Chiunque può leggere le issue lì, quindi ometti codice, trascrizioni e qualsiasi altra informazione riservata.
• Dopo un rifiuto precedente, attendi che siano trascorsi i sette giorni, quindi invia di nuovo una segnalazione per verificare se il servizio la rifiuta ancora

Prima della v2.1.319, un rifiuto precedente non produceva questo messaggio.

Prima della v2.1.302, il messaggio completo era /feedback is disabled by your organization's policy. Contact your organization admin to enable it.

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:

• Per mantenere un marketplace che un file di impostazioni dichiara inline con "source": "settings", rinominalo prima di rimuovere il vecchio nome, perché la rimozione del marketplace elimina anche la sua voce dai tuoi file di impostazioni. Claude Code v2.1.292 o successivo elenca questi passaggi nel messaggio:
  1. In ogni file di impostazioni che elenca il marketplace sotto extraKnownMarketplaces, assegna alla chiave della voce e al suo source.name un unico nuovo nome in ASCII semplice che non sembri uno ufficiale. Se un amministratore aggiunge il marketplace tramite le impostazioni gestite della tua organizzazione, è l'amministratore a eseguire questo passaggio
  2. Esegui claude plugin marketplace remove <old-name>, oppure rimuovi il vecchio nome nella scheda Marketplaces di /plugin. Questo disinstalla anche i suoi plugin ed elimina i loro dati, opzioni e segreti
  3. Avvia di nuovo Claude Code, nella cartella del progetto se il file è un file di impostazioni di progetto. Quindi installa i plugin dal marketplace rinominato
• Per mantenere qualsiasi altro marketplace, attendi fino a quando il suo manutentore lo rinomina, quindi esegui claude plugin marketplace update <name>
• Per rimuovere il marketplace, esegui claude plugin marketplace remove <name>. Questo disinstalla anche i plugin installati dal marketplace ed elimina i loro dati, opzioni e segreti
• 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 indicato una nuova fonte di marketplace con --marketplace <source> nel comando di installazione, in una sessione o dalla tua shell. Il catalogo che Claude Code ha recuperato da quella fonte ha lo stesso nome di 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

Uno dei percorsi dei componenti del plugin porta al di fuori della directory del plugin oppure non è stato possibile confermare che si trovi al suo interno, quindi Claude Code elimina quel percorso e carica il resto del plugin. Per un percorso che il plugin dichiara in plugin.json o nella sua voce del marketplace, il nome del componente nel messaggio, come commands o hooks, indica 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

Un messaggio che riporta il percorso completo di uno dei file propri di un plugin del marketplace, come hooks/hooks.json, significa che Claude Code ha saltato quel file. Questo accade quando Claude Code non riesce a confermare che il file si trovi all'interno del plugin o, per un plugin in un marketplace locale, all'interno di quel marketplace. Il messaggio segnala ciascuno di questi file sotto il nome del componente indicato:

• hooks/hooks.json: hooks
• monitors/monitors.json: monitors
• settings.json: settings
• SKILL.md alla radice del plugin: skills

Ad esempio, questo messaggio riguarda un hooks/hooks.json che si risolve al di fuori sia del plugin sia del suo marketplace locale:

hooks path escapes plugin directory: /home/user/my-marketplace/my-plugin/hooks/hooks.json — it resolves to /home/user/dotfiles/hooks.json, outside the plugin directory and its marketplace 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 sui percorsi dichiarati dal plugin guardava solo la grafia del percorso, non dove porta un collegamento simbolico.

Cosa fare:

• Se hai installato il plugin e non lo mantieni, segnala il messaggio al suo autore
• Per un percorso che il plugin dichiara, sposta il file referenziato all'interno della directory del plugin e punta il percorso ad esso con un percorso relativo ./
• Se il percorso, o una cartella sopra di esso all'interno del plugin, è un collegamento simbolico che porta al di fuori del plugin, sostituisci il collegamento simbolico con una copia di ciò a cui punta
• Se il messaggio dice che un percorso dichiarato dal plugin contiene una barra rovesciata, scrivi il percorso con barre in avanti, ad esempio ./commands/deploy.md
• Se il messaggio termina con EACCES, ripristina il tuo permesso di esecuzione su ogni directory che porta al file o alla cartella indicati dal percorso. Controlla le directory sopra il percorso, quindi segui ogni collegamento simbolico che incontri e controlla le directory che portano a dove punta. Per qualsiasi altro codice di errore, cercalo tra le cause e i passaggi per un percorso che non è stato possibile controllare.
• Per condividere file con altri plugin nello stesso marketplace, collegali con un symlink all'interno della directory del plugin, seguendo le regole del symlink

Percorso del file del server non letto

Il messaggio path not read significa che Claude Code non ha letto un file di server MCP o LSP indicato da un plugin, a causa del percorso del file. Il resto del plugin si carica, senza i server definiti dal file.

Una parte .. conta anche quando il percorso rimane all'interno del plugin, come in questo esempio:

mcp-servers path not read: ./sub/../x.json is absolute or has a ".." part

Cosa fare:

• Se hai installato il plugin e non lo mantieni, segnala il messaggio al suo autore
• Se mantieni il plugin, tieni il file del server all'interno della directory del plugin. Indicalo nel manifest o nella voce del marketplace con un percorso che inizia con ./ e non contiene .., ad esempio ./servers/x.json
• Per condividere un file del server tra plugin dello stesso marketplace, collega il file in ciascun plugin con un collegamento simbolico, seguendo le regole dei collegamenti simbolici

Plugin non caricato: il suo manifest non è stato letto

Claude Code non è riuscito a confermare che il manifest di un plugin del marketplace in .claude-plugin/plugin.json si trovi all'interno del plugin, quindi non carica nulla da quel plugin. Per un plugin in un marketplace locale, Claude Code non è inoltre riuscito a confermare che il manifest si trovi all'interno di quel marketplace. Il messaggio appare nella scheda Errors di /plugin, e il motivo alla sua fine indica cosa ha trovato Claude Code.

Ad esempio, questo messaggio riguarda un plugin in un marketplace locale la cui cartella .claude-plugin è un collegamento simbolico che porta al di fuori del marketplace:

Plugin not loaded: its manifest /home/user/my-marketplace/my-plugin/.claude-plugin/plugin.json was not read, because it resolves to /home/user/dotfiles/my-plugin/.claude-plugin/plugin.json, outside the plugin directory and its marketplace directory

Cosa fare:

• Se il motivo termina con EACCES, ripristina il tuo permesso di esecuzione su ogni directory che porta al manifest. Controlla le directory sopra il manifest, quindi segui ogni collegamento simbolico che incontri e controlla le directory che portano a dove punta. Per qualsiasi altro codice di errore, cercalo tra le cause e i passaggi per un percorso che non è stato possibile controllare.
• Se mantieni il plugin e il motivo indica dove si risolve il manifest, la cartella .claude-plugin o lo stesso plugin.json è un collegamento simbolico che porta lì. Sostituisci quel collegamento con una copia di ciò a cui punta.
• Se hai installato il plugin e non lo mantieni, segnala il messaggio al suo autore

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

Skipping connection (recent failure cached; retries automatically in 15 min, or edit the plugin config to retry now)

Questo messaggio significa che Claude Code non ha avviato un server MCP stdio fornito da un plugin, perché una connessione a quel server non è riuscita meno di 15 minuti prima:

Skipping connection (recent failure cached; retries automatically in 15 min, or edit the plugin config to retry now)

La sessione continua senza gli strumenti del server, e Claude Code non riprova il server in quella sessione allo scadere dei 15 minuti. Quando avvii una nuova sessione o un'esecuzione di claude -p almeno 15 minuti dopo la connessione non riuscita più recente, Claude Code riprova il server.

Cosa fare:

Per far riprovare il server a Claude Code senza aspettare:

• In una sessione interattiva: esegui /mcp, seleziona il server e seleziona Reconnect
• In un'applicazione Agent SDK: chiama reconnectMcpServer() in TypeScript o ClaudeSDKClient.reconnect_mcp_server() in Python con il nome del server
• In claude -p: avvia una sessione interattiva che carica lo stesso plugin, sulla stessa macchina e con lo stesso account del sistema operativo e lo stesso valore di CLAUDE_CONFIG_DIR delle tue esecuzioni. Riconnetti lì il server da /mcp. Una volta che si connette, Claude Code prova la connessione nella tua esecuzione successiva.
• Se stai sviluppando il plugin: modifica command, args o env del server nel file .mcp.json o plugin.json del plugin. Claude Code prova la connessione nella sessione o nell'esecuzione di claude -p successiva che carica la voce modificata.

Il messaggio sostituisce l'errore della connessione non riuscita. Se anche il nuovo tentativo non riesce, Claude Code segnala l'errore di quel tentativo al posto di questo messaggio.

Errori degli strumenti

Questi errori derivano dalle chiamate agli strumenti di Claude. Claude corregge da solo la maggior parte degli errori degli strumenti. Quando un errore richiede una modifica da parte tua, l'elenco Cosa fare di quell'errore indica cosa cambiare.

No such tool available

Claude ha chiamato uno strumento con un nome che non è presente nell'elenco degli strumenti della sessione. Claude Code restituisce l'errore a Claude come risultato della chiamata allo strumento e il turno prosegue. Quando Claude Code riesce a capire perché lo strumento manca, aggiunge dopo il nome dello strumento una frase che indica il motivo o nomina lo strumento da chiamare al suo posto, come nella seconda riga:

Error: No such tool available: <tool name>
Error: No such tool available: read. Tool names are case-sensitive: call Read instead.

Subito dopo aver ripreso una sessione, un server MCP può trovarsi ancora al primo tentativo di connessione quando Claude chiama uno dei suoi strumenti. Claude Code allora attende il server e restituisce questo errore se lo strumento non è ancora disponibile al termine dell'attesa. Prima della v2.1.284, una chiamata di questo tipo falliva immediatamente invece di attendere.

Anche una chiamata il cui nome dello strumento è stato troncato da Claude Code a 200 caratteri fallisce con questo errore.

Cosa fare:

• Se succede una volta sola, non devi fare nulla. Claude legge l'errore e il turno prosegue.
• Se le chiamate agli strumenti di un server MCP continuano a fallire con questo errore, esegui /mcp nella sessione o claude mcp list nella tua shell per controllare lo stato del server, e riconnetti un server non riuscito da /mcp. Nell'Agent SDK, consulta Gestione degli errori.

MCP server connection closed before the tool call was answered

Una chiamata a uno strumento di un server MCP HTTP o di un connettore di claude.ai ha perso la connessione prima che il server rispondesse, quindi Claude Code non può sapere se lo strumento è stato eseguito:

MCP server "<name>" connection closed before the tool call was answered. The tool may have run: check whether it did before running it again.

Ripetere la chiamata potrebbe ripetere l'azione dello strumento, ad esempio creando una seconda issue. Per questo Claude Code ripete la chiamata da solo, una sola volta, quando il server contrassegna lo strumento come sicuro da ripetere.

Cosa fare:

• Verifica nel servizio su cui agisce lo strumento se l'azione è avvenuta, ad esempio se la issue o il record che doveva creare è presente
• Se l'azione è avvenuta, non eseguire di nuovo lo strumento. Claude ha ricevuto questo messaggio al posto del risultato dello strumento, quindi comunica a Claude l'esito.
• Se l'azione non è avvenuta, chiedi a Claude di eseguire di nuovo lo strumento. Non devi prima riconnettere il server, perché Claude Code si riconnette al server alla successiva chiamata a uno dei suoi strumenti. Se anche quella connessione fallisce, consulta Interruzioni di un server remoto durante la sessione.
• Se sei tu a sviluppare il server e lo strumento è sicuro da chiamare due volte, contrassegnalo come sicuro da ripetere in modo che Claude Code possa ripetere una chiamata persa