Dépannage

Corrigez l'utilisation élevée du CPU ou de la mémoire, les blocages, le thrashing de l'auto-compaction et les problèmes de recherche dans Claude Code, et trouvez la bonne page pour d'autres problèmes.

Cette page couvre les problèmes de performance, de stabilité et de recherche une fois que Claude Code est en cours d'exécution. Pour d'autres problèmes, commencez par la page qui correspond à votre situation :

Si vous n'êtes pas sûr de ce qui s'applique, exécutez /doctor dans Claude Code pour une vérification automatisée de votre installation, vos paramètres, vos extensions et votre utilisation du contexte ; il propose des corrections qu'il peut appliquer après votre confirmation. Si claude ne démarre pas du tout, exécutez claude doctor depuis votre shell à la place. Exécutez /mcp pour vérifier l'état du serveur MCP.

Performance et stabilité

Ces sections couvrent les problèmes liés à l'utilisation des ressources, la réactivité et le comportement de recherche.

Utilisation élevée du CPU ou de la mémoire

Claude Code est conçu pour fonctionner avec la plupart des environnements de développement, mais peut consommer des ressources importantes lors du traitement de grandes bases de code. Si vous rencontrez des problèmes de performance :

1. Utilisez /compact régulièrement pour réduire la taille du contexte. S'il retourne Not enough messages to compact., la conversation a trop peu de tours à résumer ; cela peut se produire même avec un contexte complet quand un seul grand collage l'a rempli
2. Fermez et redémarrez Claude Code entre les tâches majeures
3. Envisagez d'ajouter les grands répertoires de construction à votre fichier .gitignore
4. Redémarrez avec claude --safe-mode pour vérifier si un plugin, un serveur MCP ou un hook est la source. Cela désactive toutes les personnalisations pour la session ; si l'utilisation diminue, consultez Déboguer votre configuration pour trouver lequel

Si l'utilisation de la mémoire reste élevée après ces étapes, exécutez /heapdump pour écrire deux fichiers sur ~/Desktop : un snapshot de tas JavaScript nommé <session-id>.heapsnapshot et une ventilation de la mémoire nommée <session-id>-diagnostics.json. Claude Code masque la commande du menu de commandes ; tapez-la en entier. Sur Linux sans dossier Desktop, les fichiers sont écrits dans votre répertoire personnel.

La commande imprime également un résumé dans la conversation, affichant la taille de l'ensemble résidant, le tas JS, les tampons de tableau et la mémoire native non comptabilisée, plus tous les indicateurs de fuite qu'elle a détectés, comme un taux de croissance de la mémoire élevé ou un nombre inhabituellement élevé de handles ouverts. Le résumé indique si la plupart de la mémoire se trouve dans le tas JS, que le snapshot capture, ou dans la mémoire native, qu'il ne capture pas.

Faites l'une de ces deux choses avec la sortie :

• Signalez-le : ouvrez un problème GitHub et attachez uniquement le fichier -diagnostics.json, qui contient les statistiques derrière le résumé imprimé et aucun contenu de conversation ou identifiants
• Enquêtez vous-même : si le résumé indique que la plupart de la mémoire se trouve dans le tas JS, ouvrez le fichier .heapsnapshot dans Chrome DevTools sous Memory → Load et triez par taille retenue pour voir ce qui retient la mémoire

Si le résumé indique que la plupart de la mémoire est native, le snapshot ne peut pas le montrer ; incluez plutôt les indicateurs de fuite du résumé dans votre rapport.

Les grandes tables sont coupées dans le terminal

Un tableau Markdown avec plus de 200 lignes affiche ses 200 premières lignes suivies d'une ligne … N more rows not shown. Seul l'affichage est limité : le tableau complet reste dans la conversation, et /copy copie chaque ligne. Pour un tableau trop volumineux pour être lu dans le terminal, demandez à Claude de l'écrire dans un fichier à la place. Avant la v2.1.208, Claude Code affichait chaque ligne, donc reprendre une session qui contenait un très grand tableau pouvait se bloquer lors du re-rendu.

L'auto-compaction s'arrête avec une erreur de thrashing

Si vous voyez Autocompact is thrashing: the context refilled to the limit..., la compaction automatique a réussi mais un fichier ou une sortie d'outil a immédiatement rempli la fenêtre de contexte plusieurs fois de suite. Claude Code arrête les tentatives pour éviter de gaspiller les appels API sur une boucle qui ne progresse pas.

Pour récupérer :

1. Demandez à Claude de lire le fichier surdimensionné en petits morceaux, comme une plage de lignes spécifique ou une fonction, au lieu du fichier entier
2. Exécutez /compact avec un focus qui supprime la sortie volumineuse, par exemple /compact keep only the plan and the diff
3. Déplacez le travail sur fichier volumineux vers un sous-agent pour qu'il s'exécute dans une fenêtre de contexte séparée
4. Exécutez /clear si la conversation antérieure n'est plus nécessaire

Les commandes se figent ou se gèlent

Si Claude Code semble ne pas répondre :

1. Appuyez sur Ctrl+C pour tenter d'annuler l'opération actuelle
2. Si ne répond pas, vous devrez peut-être fermer le terminal et redémarrer

Le redémarrage ne perd pas votre conversation. Exécutez claude --resume dans le même répertoire pour reprendre la session.

Texte garbled ou corrompu dans le terminal intégré d'un éditeur

Si les caractères s'affichent sous forme de boîtes, de traînées ou de glyphes incorrects lors de l'exécution de Claude Code dans le terminal intégré de VS Code, Cursor ou Devin Desktop, le rendu GPU du terminal en est probablement la cause. Exécutez /terminal-setup dans Claude Code pour définir terminal.integrated.gpuAcceleration sur "off", ou définissez-le manuellement dans les paramètres de votre éditeur et rechargez la fenêtre. Consultez Configuration du terminal pour les autres paramètres que /terminal-setup écrit.

La molette de la souris fait défiler une ligne à la fois dans le rendu en plein écran

Dans le rendu en plein écran, Claude Code fait défiler la conversation elle-même plutôt que de la laisser à votre terminal. Si chaque cran de molette déplace moins de lignes que vous le souhaitez, exécutez /scroll-speed pour augmenter le nombre de lignes par cran et l'enregistrer, ou définissez la variable d'environnement CLAUDE_CODE_SCROLL_SPEED, sauf dans le terminal de l'IDE JetBrains, où Claude Code applique sa propre gestion du défilement et ni l'un ni l'autre ne prend effet. Consultez Défilement à la molette de la souris pour les valeurs que chacun accepte.

Pour vous déplacer plus rapidement sans changer la vitesse, appuyez sur PgUp et PgDn pour faire défiler demi-écran à la fois. Pour rendre le défilement à votre scrollback natif du terminal à la place, exécutez /tui default pour basculer vers le rendu classique.

Les commandes du presse-papiers telles que `pbcopy` échouent à l'intérieur du sandbox

Quand le sandboxing est activé, les utilitaires du presse-papiers tels que pbcopy, xclip et wl-copy peuvent échouer à atteindre le presse-papiers système depuis une commande Bash en sandbox, laissant votre presse-papiers inchangé après que Claude ait canalisé du texte vers eux.

Pour mettre la sortie de Claude sur votre presse-papiers, demandez à Claude d'imprimer le contenu dans sa réponse, puis exécutez /copy. /copy écrit dans le presse-papiers depuis le processus Claude Code lui-même plutôt que depuis une commande en sandbox, donc le sandboxing ne le bloque pas. Il peut copier un seul bloc de code au lieu de la réponse entière, et il écrit également ce qu'il a copié dans un fichier et imprime le chemin, ce qui vous donne une solution de secours quand l'écriture du presse-papiers n'atteint pas votre terminal, par exemple sur SSH.

Pour laisser une commande canalisée atteindre le presse-papiers directement à la place, ajoutez pbcopy *, wl-copy * ou xclip * à excludedCommands pour que la commande s'exécute en dehors du sandbox.

Texte copié n'atteint pas votre presse-papiers local sur SSH

Quand Claude Code s'exécute sur une machine distante via SSH, il ne peut pas exécuter un outil de presse-papiers sur votre machine locale. En dehors de tmux, quand vous sélectionnez du texte dans le rendu en plein écran ou exécutez /copy, Claude Code envoie le texte à votre terminal en tant que séquence d'échappement OSC 52 à la place. Votre terminal décide s'il faut le mettre sur votre presse-papiers. /copy signale Copied to clipboard que le texte soit arrivé ou non, et en dehors de tmux l'avis de sélection lit sent N chars via OSC 52.

Certains terminaux n'agissent pas sur OSC 52. iTerm2 l'ignore jusqu'à ce que vous activiez Settings > General > Selection > Applications in terminal may access clipboard, et macOS Terminal.app ne le supporte pas.

Pour obtenir le texte sans OSC 52 :

• Maintenez la touche de sélection native de votre terminal pendant que vous faites glisser, puis copiez avec le raccourci habituel de votre terminal, tel que Cmd+C. La touche est Fn dans Terminal.app et Option dans iTerm2. Garder la sélection de texte native la liste pour les autres terminaux.
• Définissez CLAUDE_CODE_DISABLE_MOUSE=1 sur la machine distante pour que votre terminal gère la sélection pour la session entière.

Problèmes de recherche et de découverte

Si l'outil Search, les mentions @file, les agents personnalisés ou les compétences personnalisées ne trouvent pas les fichiers, le binaire ripgrep fourni peut ne pas s'exécuter sur votre système. Installez le paquet ripgrep de votre plateforme et dites à Claude Code de l'utiliser à la place :

brew install ripgrep

sudo apt install ripgrep

apk add ripgrep

pacman -S ripgrep

winget install BurntSushi.ripgrep.MSVC

Ensuite, définissez USE_BUILTIN_RIPGREP sur 0, soit dans votre environnement shell, soit dans le bloc env de votre settings.json :

{
  "env": {
    "USE_BUILTIN_RIPGREP": "0"
  }
}

Pour confirmer que le changement a pris effet, exécutez claude doctor dans votre terminal et vérifiez que la ligne Search affiche le chemin de votre ripgrep système au lieu de OK (bundled).

Résultats de recherche lents ou incomplets sur WSL

Les pénalités de performance de lecture de disque lors du travail sur les systèmes de fichiers sur WSL peuvent entraîner moins de correspondances que prévu lors de l'utilisation de Claude Code sur WSL. La recherche fonctionne toujours, mais retourne moins de résultats que sur un système de fichiers natif.

Solutions :

1. Soumettre des recherches plus spécifiques : réduisez le nombre de fichiers recherchés en spécifiant des répertoires ou des types de fichiers : « Search for JWT validation logic in the auth-service package » ou « Find use of md5 hash in JS files ».

2. Déplacer le projet vers le système de fichiers Linux : si possible, assurez-vous que votre projet est situé sur le système de fichiers Linux (/home/) plutôt que sur le système de fichiers Windows (/mnt/c/).

3. Utiliser Windows natif à la place : envisagez d'exécuter Claude Code nativement sur Windows au lieu de via WSL, pour une meilleure performance du système de fichiers.

Obtenir plus d'aide

Si vous rencontrez des problèmes non couverts ici :

1. Exécutez /doctor pour une vérification de la configuration et /mcp pour vérifier l'état du serveur MCP
2. Utilisez la commande /feedback dans Claude Code pour signaler les problèmes directement à Anthropic
3. Vérifiez le référentiel GitHub pour les problèmes connus
4. Demandez directement à Claude ses capacités et fonctionnalités. Claude a un accès intégré à sa documentation.

Pour les problèmes de compte, de facturation ou d'abonnement, contactez le support Anthropic à la place : connectez-vous à claude.ai (Utilisateurs Console : platform.claude.com), cliquez sur vos initiales en bas à gauche, et sélectionnez Obtenir de l'aide. Consultez Comment obtenir du support pour le flux complet, y compris qui peut vous mettre en contact avec un agent humain selon votre plan.