Passa al contenuto principale

Risoluzione dei problemi di Claude Code

Intermedio
What you'll learn
  • Indirizzare qualsiasi problema di Claude Code alla sua soluzione in un solo passaggio, usando una tabella dei sintomi
  • Eseguire i due comandi diagnostici che risolvono la maggior parte dei problemi di configurazione, prima di mettersi a debuggare a mano
  • Isolare se la causa reale è un plugin, un server MCP o un hook
  • Risolvere i quattro classici guasti a runtime: memoria elevata, blocchi, thrashing della compattazione e ricerca che non trova nulla
  • Raccogliere le prove giuste prima di aprire una segnalazione di bug

L'idea di fondo​

Quasi ogni problema di Claude Code è di uno di due tipi, e hanno soluzioni completamente diverse:

  • La tua configurazione è sbagliata — un plugin, un server MCP, un hook, un file di impostazioni, un binario mancante. La soluzione è configurazione.
  • La sessione è sotto sforzo — la finestra di contesto è piena, un file enorme ha fatto esplodere la memoria, il terminale non riesce a renderizzare. La soluzione è igiene.

È tirando a indovinare su quale dei due sia che si perde un pomeriggio. La tabella qui sotto elimina il tirare a indovinare.

:::tip Un tipo di "stranezza" diverso? Questa pagina riguarda lo strumento che si comporta male — non parte, si blocca, la ricerca non trova nulla. Se è il modello a comportarsi male — si è inventato un fatto, ha dimenticato un'istruzione, ha rifiutato qualcosa di ragionevole — quella è un'altra pagina: Perché Claude ha fatto così? :::

Parti da qui: sintomo → dove andare​

Trova il tuo sintomo. Non leggere il resto della pagina.

SintomoVai a
command not found, installazione fallita, EACCES, errori di PATH o TLSUfficiale: installazione e login
Login in loop, errori OAuth, 403 Forbidden, "organization disabled"Ufficiale: login e autenticazione
Impostazioni che non vengono applicate, hook che non scattano, server MCP che non si caricanoIsola la tua configurazione qui sotto
API Error: 5xx, 529 Overloaded, 429, errori di validazioneErrori e limiti di frequenza
model not found / "you may not have access to it"Modelli e prezzi attuali
VS Code o JetBrains non rilevano ClaudeIntegrazioni IDE
CPU o memoria elevateMemoria e CPU qui sotto
Blocchi, freeze, mancate risposteBlocchi e freeze qui sotto
Autocompact is thrashingThrashing della compattazione qui sotto
La ricerca, @file, gli agent o le skill non trovano i fileLa ricerca non trova nulla qui sotto
Riquadri, sbavature o glifi sbagliati nel terminale dell'IDETesto illeggibile nel terminale qui sotto

I due comandi da eseguire per primi​

Prima di metterti a debuggare a mano, esegui il checkup integrato. Diagnostica installazione, impostazioni, estensioni e uso del contesto — e propone correzioni che può applicare dopo la tua conferma.

Guided walkthrough1 of 3
  1. /doctor (il suo alias è /checkup) ispeziona installazione, impostazioni, estensioni e uso del contesto, poi si offre di applicare le correzioni che può. Solo questo risolve la maggior parte delle lamentele sulla configurazione.

Diagnosticare una configurazione rotta

# inside a session
/doctor

# if the session won't start at all
claude doctor

# check MCP server status
/mcp

Isola la tua configurazione​

Se le impostazioni non vengono applicate, gli hook non scattano o c'è semplicemente qualcosa che non va, la domanda non è mai "cosa è rotto" — è quale delle tue personalizzazioni è rotta. Rispondi rimuovendole tutte in una volta.

--safe-mode avvia Claude Code con ogni personalizzazione disabilitata: niente plugin, niente server MCP, niente hook.

Testare con una configurazione pulita

claude --safe-mode

Questo ti dà un risultato binario e netto:

Una volta che sai che è una personalizzazione, fai bisezione: riabilitale a gruppi finché il problema non ritorna. I sospetti, in ordine approssimativo di quanto spesso sono i colpevoli, sono i server MCP, gli hook, i plugin e le impostazioni.

Pro tip
  • --safe-mode è la prima mossa giusta anche per lentezze misteriose, non solo per i guasti conclamati. Un server MCP troppo chiacchierone è una causa molto comune di entrambi.

Memoria e CPU​

Claude Code funziona con la maggior parte degli ambienti, ma su codebase grandi può consumare risorse reali. Affronta questi punti in ordine — sono ordinati dal più economico.

Guided walkthrough1 of 5
  1. Esegui /compact per ridurre il contesto. Una finestra di contesto gonfia è di gran lunga la causa più comune di una sessione pesante. Vedi /docs/claude-code/context-management.

Il riepilogo di /heapdump riporta resident set size, heap JS, array buffer e memoria nativa non attribuita. Quella suddivisione è la parte utile: ti dice se la crescita è negli oggetti JavaScript o giù nel codice nativo. Per ispezionare cosa tiene viva la memoria, apri il file .heapsnapshot in Chrome DevTools sotto Memory → Load.

Blocchi e freeze​

Se Claude Code smette di rispondere:

Guided walkthrough1 of 3
  1. Premi Ctrl+C. Questo interrompe qualunque cosa sia in esecuzione senza uccidere la sessione.
Pro tip
  • La paura di perdere una conversazione lunga è il motivo per cui si aspetta la fine di un blocco invece di ucciderlo. Non farlo — claude --resume nella stessa directory riporta indietro la sessione.

Thrashing della compattazione​

Questo errore sembra allarmante ed è in realtà una protezione:

Autocompact is thrashing: the context refilled to the limit...

Significa che la compattazione automatica è riuscita — e poi un file o l'output di un tool ha immediatamente riempito di nuovo l'intera finestra di contesto, diverse volte di fila. Claude Code smette di riprovare invece di bruciare chiamate API su un loop che non sta facendo progressi.

La causa è quasi sempre una singola cosa sovradimensionata letta per intero. Scegli la soluzione adatta alla tua situazione:

SituazioneSoluzione
Il problema è un singolo file enormeChiedi a Claude di leggere un intervallo di righe o una singola funzione invece dell'intero file
Il contesto contiene un output grande che non ti serve più/compact con un focus che lo scarta
La lettura grande è davvero necessariaSpostala su un subagent, così brucia una finestra di contesto separata
La conversazione precedente non conta più/clear

Compattare con un focus che scarta il superfluo

/compact keep only the plan and the diff

L'opzione subagent è quella che si dimentica, ed è spesso la migliore: un subagent legge il file gigante nel suo contesto e restituisce al tuo solo la conclusione. Vedi Gestione del contesto e Subagent.

La ricerca non trova nulla​

Se il tool Search, le menzioni @file, gli agent personalizzati o le skill personalizzate non trovano file che sai esistere, probabilmente il binario ripgrep incluso non riesce a girare sul tuo sistema. La soluzione è installare il ripgrep della tua piattaforma e dire a Claude Code di usare quello.

Guided walkthrough1 of 3
  1. macOS: brew install ripgrep — Ubuntu/Debian: sudo apt install ripgrep — Alpine: apk add ripgrep — Arch: pacman -S ripgrep — Windows: winget install BurntSushi.ripgrep.MSVC

Sistemare la ricerca su macOS

brew install ripgrep
export USE_BUILTIN_RIPGREP=0

L'eccezione WSL​

Su WSL, i risultati di ricerca incompleti in genere non sono un binario rotto. Leggere attraverso il confine tra filesystem Windows e Linux comporta una penalità di prestazioni sul disco, quindi la ricerca restituisce meno corrispondenze del previsto. La ricerca funziona comunque — semplicemente rende meno del dovuto.

Watch out
  • Su WSL, claude doctor riporta Search come OK anche mentre i risultati sono incompleti. Un checkup verde non esclude questo caso — ed è esattamente ciò che lo rende difficile da diagnosticare.

Tre vie d'uscita, dalla migliore: sposta il progetto sul filesystem Linux (/home/) invece che su /mnt/c/; esegui Claude Code nativamente su Windows invece che tramite WSL; oppure restringi le ricerche così da scandire meno file — "Search for JWT validation logic in the auth-service package" batte "find the auth code".

Testo illeggibile nel terminale​

Caratteri che vengono renderizzati come riquadri, sbavature o glifi sbagliati dentro il terminale integrato di VS Code, Cursor o Devin Desktop sono un problema del renderer GPU, non un problema di font o di codifica.

Sistemare i glifi illeggibili in un terminale IDE

/terminal-setup

Questo imposta terminal.integrated.gpuAcceleration su "off". In alternativa puoi impostarlo a mano nelle impostazioni dell'editor e ricaricare la finestra — stesso risultato.

Le tabelle grandi vengono troncate​

Una tabella Markdown oltre le 200 righe renderizza le prime 200 seguite da una riga … N more rows not shown. Questo è solo un limite di visualizzazione — la tabella completa è ancora nella conversazione, e /copy copia ogni riga. Per una tabella troppo grande da leggere in un terminale, chiedi a Claude di scriverla su un file.

Scrivere una buona segnalazione di bug​

Se qui non c'è nulla che ti calzi, segnalalo — ma porta prove. Una segnalazione che dice "è lento" non porta da nessuna parte; una con uno snapshot dell'heap e un risultato in --safe-mode viene risolta.

Guided walkthrough1 of 4
  1. Cattura cosa dice il checkup e quali server MCP sono effettivamente caricati. Metà dei bug segnalati trova risposta qui.
Key takeaways
  • Esegui prima /doctor (alias /checkup) — dalla shell come claude doctor se la sessione non parte. Diagnostica installazione, impostazioni, estensioni e uso del contesto, e può applicare correzioni.
  • claude --safe-mode disabilita tutte le personalizzazioni in una volta. Che il problema sopravviva o no è il dato più informativo che tu possa raccogliere.
  • Memoria elevata: /compact, riavvia tra un task e l'altro, metti le directory di build in .gitignore, poi --safe-mode, poi /heapdump per le prove.
  • Un blocco non è una conversazione persa — Ctrl+C, poi riavvia il terminale, poi claude --resume nella stessa directory.
  • Il thrashing dell'autocompact significa che una lettura sovradimensionata riempie di nuovo la finestra. Leggi a pezzi, /compact con un focus, o delega la lettura a un subagent.
  • La ricerca che non trova nulla di solito significa che il ripgrep incluso non riesce a girare: installa il ripgrep della tua piattaforma E imposta USE_BUILTIN_RIPGREP=0. Su WSL è invece una penalità del confine tra filesystem — e claude doctor riporta comunque Search come OK.

Verifica le tue conoscenze

0/5
  1. Gli hook non scattano e le impostazioni sembrano ignorate. Qual è la singola cosa più informativa da provare?
  2. Claude Code si blocca a metà task e Ctrl+C non aiuta. Chiudi il terminale. Che ne è della tua conversazione?
  3. Vedi 'Autocompact is thrashing: the context refilled to the limit...'. Cosa è successo davvero?
  4. Hai installato ripgrep con brew perché le menzioni @file non trovavano nulla, ma la ricerca è ancora rotta. Cosa ti sei perso?
  5. Su WSL la ricerca restituisce meno corrispondenze del previsto ma claude doctor riporta Search come OK. Cosa sta succedendo?

Prossimi passi​