Aller au contenu principal

Dépanner Claude Code

Intermédiaire
What you'll learn
  • Router n'importe quel problème de Claude Code vers son correctif en une étape, à l'aide d'une table des symptômes
  • Lancer les deux commandes de diagnostic qui résolvent la plupart des soucis de configuration avant de déboguer quoi que ce soit à la main
  • Isoler si un plugin, un serveur MCP ou un hook est la vraie cause
  • Corriger les quatre défaillances classiques d'exécution : mémoire élevée, blocages, thrashing de compaction et recherche qui ne trouve rien
  • Rassembler les bonnes preuves avant de déposer un rapport de bug

L'idée principale​

Presque tout problème de Claude Code est de l'une des deux sortes, et elles ont des correctifs complètement différents :

  • Votre configuration est mauvaise — un plugin, un serveur MCP, un hook, un fichier de settings, un binaire manquant. Le correctif est la configuration.
  • La session est sous tension — la fenêtre de contexte est pleine, un fichier énorme a fait exploser la mémoire, le terminal n'arrive pas à afficher. Le correctif est l'hygiène.

Deviner laquelle vous avez est là où les gens perdent une après-midi. La table ci-dessous saute l'étape des devinettes.

:::tip Un genre de « bizarre » différent ? Cette page concerne l'outil qui se comporte mal — il ne démarre pas, il se bloque, la recherche ne trouve rien. Si le modèle se comporte mal — il a inventé un fait, oublié une instruction, refusé quelque chose de raisonnable — c'est une autre page : Pourquoi Claude a-t-il fait ça ? :::

Commencez ici : symptôme → où aller​

Trouvez votre symptôme. Ne lisez pas le reste de la page.

SymptômeAller à
command not found, échec d'installation, EACCES, erreurs de PATH ou TLSOfficiel : installation & connexion
Boucles de connexion, erreurs OAuth, 403 Forbidden, « organization disabled »Officiel : connexion & authentification
Settings non appliqués, hooks qui ne se déclenchent pas, serveurs MCP qui ne se chargent pasIsoler votre configuration ci-dessous
API Error: 5xx, 529 Overloaded, 429, erreurs de validationErreurs & limites de débit
model not found / « you may not have access to it »Modèles & tarifs actuels
VS Code ou JetBrains ne détecte pas ClaudeIntégrations IDE
CPU ou mémoire élevésMémoire et CPU ci-dessous
Blocages, gels, absence de réponseBlocages et gels ci-dessous
Autocompact is thrashingThrashing de compaction ci-dessous
Recherche, @file, agents ou skills ne trouvent pas les fichiersLa recherche ne trouve rien ci-dessous
Cases, bavures ou glyphes erronés dans un terminal d'IDETexte de terminal illisible ci-dessous

Les deux commandes à lancer en premier​

Avant de déboguer quoi que ce soit à la main, lancez le bilan intégré. Il diagnostique votre installation, vos settings, vos extensions et votre usage du contexte — et propose des correctifs qu'il peut appliquer après confirmation.

Guided walkthrough1 of 3
  1. /doctor (son alias est /checkup) inspecte votre installation, vos settings, vos extensions et votre usage du contexte, puis propose d'appliquer les correctifs qu'il peut. À lui seul, il résout la plupart des plaintes de configuration.

Diagnostiquer une configuration cassée

# inside a session
/doctor

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

# check MCP server status
/mcp

Isoler votre configuration​

Si les settings ne s'appliquent pas, si les hooks ne se déclenchent pas, ou si quelque chose est juste bizarre, la question n'est jamais « qu'est-ce qui est cassé » — c'est laquelle de vos personnalisations est cassée. Répondez-y en les retirant toutes d'un coup.

--safe-mode démarre Claude Code avec toutes les personnalisations désactivées : pas de plugins, pas de serveurs MCP, pas de hooks.

Tester contre une configuration propre

claude --safe-mode

Cela vous donne un résultat binaire net :

Une fois que vous savez que c'est une personnalisation, faites une bisection : réactivez-les par groupes jusqu'à ce que le problème revienne. Les suspects, dans l'ordre approximatif de fréquence, sont les serveurs MCP, les hooks, les plugins et les settings.

Pro tip
  • --safe-mode est aussi le bon premier réflexe pour une lenteur mystérieuse, pas seulement pour une panne franche. Un serveur MCP bavard est une cause très courante des deux.

Mémoire et CPU​

Claude Code fonctionne avec la plupart des environnements mais peut consommer de vraies ressources sur de gros codebases. Parcourez ceci dans l'ordre — c'est trié du moins coûteux au plus coûteux.

Guided walkthrough1 of 5
  1. Lancez /compact pour réduire le contexte. Une fenêtre de contexte gonflée est la cause unique la plus courante d'une session lourde. Voir /docs/claude-code/context-management.

La ventilation de /heapdump reporte la taille résidente (resident set size), le tas JS, les array buffers et la mémoire native non comptabilisée. Cette répartition est la partie utile : elle vous dit si la croissance est dans les objets JavaScript ou en bas dans le code natif. Pour inspecter ce qui maintient la mémoire en vie, ouvrez le fichier .heapsnapshot dans Chrome DevTools sous Memory → Load.

Blocages et gels​

Si Claude Code cesse de répondre :

Guided walkthrough1 of 3
  1. Appuyez sur Ctrl+C. Cela avorte ce qui tourne sans tuer la session.
Pro tip
  • La peur de perdre une longue conversation est pourquoi les gens attendent la fin d'un blocage au lieu de le tuer. Ne le faites pas — claude --resume dans le même répertoire ramène la session.

Thrashing de compaction​

Cette erreur a l'air alarmante et est en réalité une protection :

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

Elle signifie que la compaction automatique a réussi — et qu'ensuite un fichier ou une sortie d'outil a immédiatement re-rempli toute la fenêtre de contexte, plusieurs fois d'affilée. Claude Code arrête de réessayer plutôt que de brûler des appels API dans une boucle qui ne progresse pas.

La cause est presque toujours une seule chose surdimensionnée lue en entier. Choisissez le correctif qui correspond à votre situation :

SituationCorrectif
Un seul fichier énorme est le problèmeDemandez à Claude de lire une plage de lignes ou une seule fonction au lieu de tout le fichier
Le contexte a une grosse sortie dont vous n'avez plus besoin/compact avec un focus qui l'écarte
La grosse lecture est vraiment nécessaireDéplacez-la dans un subagent pour qu'elle brûle une fenêtre de contexte séparée
La conversation antérieure n'a plus d'importance/clear

Compacter avec un focus qui écarte le superflu

/compact keep only the plan and the diff

L'option subagent est celle qu'on oublie, et c'est souvent la meilleure : un subagent lit le fichier géant dans son contexte et ne renvoie que la conclusion au vôtre. Voir Gestion du contexte et Subagents.

La recherche ne trouve rien​

Si l'outil de recherche, les mentions @file, les agents personnalisés ou les skills personnalisées ne trouvent pas des fichiers dont vous savez qu'ils existent, le binaire ripgrep embarqué n'arrive probablement pas à s'exécuter sur votre système. Le correctif est d'installer le ripgrep propre à votre plateforme et de dire à Claude Code de l'utiliser.

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

Réparer la recherche sur macOS

brew install ripgrep
export USE_BUILTIN_RIPGREP=0

L'exception WSL​

Sur WSL, des résultats de recherche incomplets ne sont généralement pas un binaire cassé. Lire à travers la frontière du système de fichiers Windows/Linux entraîne une pénalité de performance disque, donc la recherche renvoie moins de correspondances que prévu. La recherche fonctionne toujours — elle sous-livre simplement.

Watch out
  • Sur WSL, claude doctor reporte Search comme OK même quand les résultats sont incomplets. Un bilan vert n'écarte pas ce cas — c'est exactement ce qui le rend difficile à diagnostiquer.

Trois issues, la meilleure en premier : déplacez le projet sur le système de fichiers Linux (/home/) plutôt que /mnt/c/ ; lancez Claude Code nativement sur Windows au lieu de passer par WSL ; ou restreignez vos recherches pour que moins de fichiers soient scannés — « Cherche la logique de validation JWT dans le paquet auth-service » bat « trouve le code d'auth ».

Texte de terminal illisible​

Des caractères qui s'affichent en cases, bavures ou glyphes erronés dans le terminal intégré de VS Code, Cursor ou Devin Desktop est un problème de rendu GPU, pas un problème de police ou d'encodage.

Réparer les glyphes illisibles dans un terminal d'IDE

/terminal-setup

Cela met terminal.integrated.gpuAcceleration à "off". Vous pouvez le définir à la main dans les settings de votre éditeur et recharger la fenêtre à la place — même résultat.

Les grandes tables sont coupées​

Une table Markdown de plus de 200 lignes affiche ses 200 premières suivies d'une ligne … N more rows not shown. C'est uniquement une limite d'affichage — la table complète est toujours dans la conversation, et /copy copie toutes les lignes. Pour une table trop grande à lire dans un terminal, demandez à Claude de l'écrire dans un fichier.

Déposer un bon rapport de bug​

Si rien ici ne colle, signalez-le — mais apportez des preuves. Un rapport qui dit « c'est lent » n'aboutit nulle part ; un avec un instantané de tas et un résultat --safe-mode se fait corriger.

Guided walkthrough1 of 4
  1. Capturez ce que dit le bilan et quels serveurs MCP sont réellement chargés. La moitié des bugs signalés trouvent leur réponse ici.
Key takeaways
  • Lancez /doctor (alias /checkup) d'abord — depuis votre shell en claude doctor si la session ne démarre pas. Il diagnostique installation, settings, extensions et usage du contexte, et peut appliquer des correctifs.
  • claude --safe-mode désactive toutes les personnalisations d'un coup. Que le problème y survive ou non est le fait unique le plus informatif que vous puissiez rassembler.
  • Mémoire élevée : /compact, redémarrer entre les tâches, .gitignore les répertoires de build, puis --safe-mode, puis /heapdump pour les preuves.
  • Un blocage n'est pas une conversation perdue — Ctrl+C, puis redémarrer le terminal, puis claude --resume dans le même répertoire.
  • Le thrashing d'autocompact signifie qu'une seule lecture surdimensionnée re-remplit la fenêtre. Lisez par morceaux, /compact avec un focus, ou déléguez la lecture à un subagent.
  • La recherche qui ne trouve rien signifie généralement que le ripgrep embarqué ne peut pas s'exécuter : installez le ripgrep de votre plateforme ET définissez USE_BUILTIN_RIPGREP=0. Sur WSL c'est plutôt une pénalité de frontière de système de fichiers — et claude doctor reporte quand même Search comme OK.

Testez-vous

0/5
  1. Les hooks ne se déclenchent pas et les settings semblent ignorés. Quelle est la chose unique la plus informative à essayer ?
  2. Claude Code se bloque en pleine tâche et Ctrl+C n'aide pas. Vous fermez le terminal. Qu'arrive-t-il à votre conversation ?
  3. Vous voyez « Autocompact is thrashing: the context refilled to the limit... ». Que s'est-il réellement passé ?
  4. Vous avez installé ripgrep avec brew parce que les mentions @file ne trouvaient rien, mais la recherche est toujours cassée. Qu'avez-vous manqué ?
  5. Sur WSL, la recherche renvoie moins de correspondances que prévu mais claude doctor reporte Search comme OK. Que se passe-t-il ?

Suite​