Résolution des problèmes courants (FAQ / Troubleshooting)

📚 Navigation de la série : Le chapitre précédent 50 Anti-patrons : les erreurs d'usage courantes a listé les pratiques d'apparence correcte mais s'avérant contre-productives. Ce chapitre aborde la résolution des problèmes — comment identifier méthodiquement la cause profonde des dysfonctionnements de Claude Code. Problèmes d'installation, de connexion, blocages de permissions, déconnexions MCP, lenteurs ou messages d'erreur explicites... Ce chapitre vous propose un guide d'orientation complet associant symptômes et solutions.

Commençons par un scénario classique pour illustrer l'objectif de ce chapitre.

Imaginez la situation suivante : vous viens de configurer un nouveau Mac et d'installer Claude Code pour le projet de votre entreprise. Au démarrage, l'outil affiche le message This organization has been disabled. Votre premier réflexe est de penser que votre compte a été bloqué ; vous vous connectez rapidement à claude.ai pour vérifier votre abonnement — tout est en ordre, votre formule Max est active. Vous suspectez ensuite un problème réseau, configurez un proxy ou un VPN, mais le message persiste. Après avoir cherché pendant près de quarante minutes et réinstallé deux fois Claude Code, vous êtes sur le point d'ouvrir un ticket d'assistance.

Quelle était la cause réelle du problème ? Lors du transfert de configuration depuis votre ancien Mac, une ligne complètement oubliée : export ANTHROPIC_API_KEY=... figurait dans votre fichier ~/.zshrc, vestige d'un ancien projet d'une entreprise fermée depuis six mois. L'existence de cette variable d'environnement a court-circuité l'authentification par abonnement, et Claude Code a utilisé cette clé obsolète, provoquant le blocage de l'organisation. Une simple commande unset ANTHROPIC_API_KEY a résolu le problème instantanément.

Cet exemple illustre une règle essentielle : la pire approche en matière de résolution de problèmes consiste à deviner. Les quarante minutes ont été perdues à spéculer sur le compte, le réseau... vous éloignant de la cause réelle. Pourtant, Claude Code intègre un outil de diagnostic simple : la commande /status vous indique instantanément les identifiants actifs. Ce chapitre vous présente une méthode structurée pour cibler et résoudre les anomalies.

À la fin de ce chapitre, vous obtiendrez :

• Un tableau d'orientation associant symptômes et actions pour cibler l'anomalie sans tâtonner
• L'usage des deux commandes de diagnostic de base : /doctor pour le bilan de santé et /feedback pour signaler une anomalie
• Une synthèse de résolutions classée en six catégories : installation, authentification, permissions, MCP, performances et messages d'erreur
• Le fonctionnement des options de débogage --debug et la méthode de comparaison avec une configuration vierge
• Un exercice pratique guidé pour réaliser le bilan de santé de votre installation avec /doctor

---

01 Règle d'or de la résolution de problèmes : identifier la catégorie de l'anomalie sans tâtonner

Le principe le plus important, bien plus que les commandes de diagnostic, est le suivant : lorsqu'une anomalie survient, la première étape consiste à identifier sa catégorie (installation, authentification, configuration ou API) avant de chercher à la corriger. Une mauvaise catégorisation conduit à des actions inutiles.

Analogie : Fermer la vanne d'arrivée d'eau avant de casser le carrelage en cas de fuite. Face à une infiltration, un plombier expérimental ne détruit pas le mur d'emblée — il cherche d'abord à savoir si la fuite provient du robinet, d'un raccord ou du voisin du dessus. Sans ce diagnostic, vous risquez de casser le sol pour rien. Pour Claude Code, le principe est identique : catégoriser d'abord, agir ensuite.

Pourquoi cette étape est-elle cruciale ? Parce que la documentation officielle de Claude Code est elle-même structurée par catégories — installation et connexion, erreurs d'exécution, configuration et débogage, performances. Si vous n'identifiez pas la catégorie de l'anomalie, vous ne saurez pas quelle page consulter. Voici le tableau d'orientation officiel adapté aux cas les plus fréquents :

Symptôme constaté	Catégorie / Référence
command not found: claude, échec d'installation, problème de PATH, erreur EACCES	Installation (voir chapitre 02 et section 02 ci-dessous)
Demandes de connexion répétées, erreur 403 Forbidden, organization disabled	Authentification et connexion (section 03 ci-dessous)
Paramètres ignorés, hooks inactifs, serveurs MCP non chargés, règles de permissions inefficaces	Configuration (section 04 ci-dessous et débogage de configuration)
Erreurs API Error: 5xx, 529 Overloaded, 429	Erreurs d'API (section 06 ci-dessous, généralement indépendant de votre fait)
model not found / you may not have access to it	Erreurs d'exécution (section 06 ci-dessous, modèle incorrect ou droits manquants)
Ralentissements, consommation CPU/mémoire élevée, fichiers introuvables lors de la recherche	Performances (section 05 ci-dessous)

L'utilisation est simple : identifiez le symptôme le plus proche dans la colonne de gauche, la colonne de droite vous indique la direction à suivre. Les sections suivantes détaillent chacune de ces catégories.

这里插一句官方的话，值得你刻在脑子里：「如果你不确定哪个适用，请在 Claude Code 内运行 /doctor 来自动检查你的安装、设置、MCP 服务器和上下文使用情况。如果 claude 根本无法启动，请从你的 shell 运行 claude doctor。」

En clair : en cas de doute sur la catégorie, n'hésitez pas, lancez d'abord /doctor pour vous orienter. La section suivante détaille ces deux commandes de diagnostic.

💡 En résumé : La première étape consiste toujours à catégoriser le problème sans agir à l'aveugle — identifiez sa nature à l'aide du tableau d'orientation avant d'intervenir ; utilisez /doctor en cas d'incertitude.

---

02 Deux commandes de diagnostic : /doctor pour le bilan de santé et /feedback pour signaler une anomalie

Avant de consulter la documentation ou de solliciter de l'aide, sachez que Claude Code intègre deux commandes d'assistance autonome. Dans 90 % des cas, soit /doctor identifiera le problème, soit vous pourrez utiliser /feedback pour le signaler. Maîtriser ces deux outils vous fera gagner beaucoup de temps.

Analogie : Réaliser un bilan de santé en cas de malaise. Face à une douleur, on ne procède pas à une opération d'emblée — on commence par des analyses (tension, rythme cardiaque, examens biologiques) qui permettent au médecin de cibler l'anomalie. La commande /doctor est ce bilan de santé pour Claude Code : en une seule commande, elle vérifie la validité de l'installation, la syntaxe de la configuration, la connexion des serveurs MCP et l'état du contexte.

/doctor : bilan de santé en un clic

La commande /doctor est le premier réflexe à adopter. Les contrôles effectués sont explicités officiellement — état de l'installation, validité des paramètres (clés incorrectes ou erreurs de schéma), configuration MCP et usage du contexte.

Deux cas de figure selon l'état de l'outil :

• L'application démarre : saisissez directement /doctor au sein de la session.
• claude refuse de démarrer (ex. command not found ou crash au lancement) : saisissez claude doctor (sans le symbole de barre oblique /) directement dans votre terminal.

La commande /doctor propose une option pratique : si une anomalie est détectée, appuyez sur la touche f pour envoyer le rapport directement à Claude, qui vous guidera pour appliquer les corrections. C'est l'équivalent d'avoir le médecin à vos côtés pour analyser les résultats du bilan.

/feedback : signaler une anomalie persistante

Si l'anomalie persiste après avoir consulté la documentation et exécuté /doctor — n'insistez pas inutilement et utilisez /feedback pour la signaler à Anthropic. Cette commande transmet l'historique des échanges accompagné de votre description ; c'est le moyen le plus rapide d'obtenir une assistance officielle (particulièrement pour les baisses de qualité de réponse inexpliquées ne générant pas de message d'erreur). Elle permet également d'ouvrir une issue GitHub préremplie. Note : si vous utilisez des serveurs tiers comme Bedrock ou Vertex, /feedback n'envoie pas de données à Anthropic mais génère une archive locale, que vous devez transmettre manuellement à votre interlocuteur Anthropic.

您可能在别处听过 /bug 这个说法——它就是「上报问题」这件事的旧叫法。现在官方统一用 /feedback：在会话里把记录和描述发给 Anthropic，或顺带开一个预填的 GitHub issue。记 /feedback 这一个就够。

Voici un tableau récapitulatif des actions à privilégier :

Situation	Action recommandée	Rôle de l'action
Incertitude sur la catégorie de l'anomalie	/doctor	Bilan de santé complet pour identifier la direction
claude refuse de démarrer	claude doctor (dans le terminal)	Diagnostic exécutable sans lancer l'application
Anomalie détectée par /doctor à faire corriger par Claude	Appuyer sur f dans le retour de /doctor	Soumettre le rapport de diagnostic à Claude
Échec des recherches et documentations	/feedback	Transmettre l'historique et la description à Anthropic
Suspicion de panne des serveurs officiels	Consulter status.claude.com dans le navigateur	Vérifier l'état de fonctionnement des API en temps réel

L'adresse status.claude.com est essentielle à retenir : lorsque vous rencontrez des erreurs de serveur de type 5xx ou 529, le premier réflexe doit être de consulter cette page de statut plutôt que de modifier vos paramètres — la cause réside fréquemment dans une instabilité côté Anthropic indépendante de votre configuration. Ce point est détaillé à la section 06.

💡 En résumé : Avant toute chose, recourez aux deux outils intégrés — /doctor (ou claude doctor dans le terminal) pour cibler le problème, et /feedback pour le signaler en cas d'échec ; consultez status.claude.com si vous suspectez une panne des serveurs.

---

03 Authentification et connexion : demandes répétées ou organisation bloquée

Nous passons en revue les anomalies par catégories, en commençant par l'authentification et la connexion — c'est le type de problème qui inquiète le plus les débutants en raison des messages d'erreur explicites (disabled, Forbidden, revoked), mais leur cause est souvent triviale.

Analogie : L'accès refusé par un badge à l'entrée de l'entreprise ne signifie pas un licenciement. Le badge a pu se démagnétiser, vous vous êtes peut-être trompé de carte, ou l'horloge du lecteur est décalée. Un message d'erreur d'accès refusé n'équivaut pas à une perte de droits. Pour les problèmes de connexion, le principe est le même — vérifiez d'abord quels identifiants Claude Code utilise réellement avant d'imaginer le pire.

Première étape : identifier les identifiants actifs

C'est le premier réflexe incontournable pour ce type d'anomalie, qui vous évitera de perdre du temps. Saisissez au sein de la session :

/status

Résultat attendu : Affichage de la méthode d'authentification active — votre abonnement (connexion OAuth) ou une clé API. Si vous disposez d'un abonnement actif mais que la console indique l'utilisation d'une clé API, vous avez identifié la cause du problème.

Le cas classique : la variable ANTHROPIC_API_KEY court-circuitant l'abonnement

C'est l'erreur illustrée en introduction. La documentation officielle l'explique clairement :

环境变量优先于 /login，因此在你的 shell 配置文件中导出或从 .env 文件加载的密钥，即使你有有效的 Pro 或 Max 订阅也会被使用。在非交互模式（-p）中，当存在密钥时总是使用该密钥。

Si votre environnement contient la variable ANTHROPIC_API_KEY (même oubliée depuis des mois), Claude Code l'utilisera par défaut. Si cette clé a expiré ou appartient à une organisation désactivée, l'erreur This organization has been disabled s'affiche. La solution :

unset ANTHROPIC_API_KEY
claude

Cependant, la commande unset ne s'applique qu'au terminal actif. Pour une correction permanente, vous devez supprimer la ligne export ANTHROPIC_API_KEY=... dans votre fichier ~/.zshrc, ~/.bashrc ou ~/.profile (sous Windows, vérifiez le profil PowerShell $PROFILE et les variables d'environnement utilisateur). Redémarrez ensuite claude et exécutez /status pour vérifier le retour à l'authentification par abonnement. Cette hiérarchie des identifiants a été abordée au chapitre 04, consultez-le en cas de doute.

Résolution des autres erreurs d'authentification courantes

Message d'erreur	Signification	Résolution
Not logged in · Please run /login	Aucun identifiant valide pour la session active	Saisir /login ; si vous utilisez l'authentification par variables d'environnement, vérifier que ANTHROPIC_API_KEY est bien exportée
OAuth token revoked / has expired	La session d'authentification enregistrée a expiré	Exécuter /login pour vous reconnecter ; si le problème persiste au sein de la session, exécuter /logout puis /login
Connexion demandée à chaque démarrage	Expiration systématique du token d'authentification	Vérifier la précision de l'horloge système (la validation du token s'appuie sur le timestamp) ; sous macOS, cela peut provenir d'un trousseau d'accès verrouillé (Keychain), lancer claude doctor
Erreur 403 Forbidden (après connexion)	Problème lié à l'abonnement, aux droits ou aux rôles	Pour les formules Pro/Max, vérifier l'abonnement sur claude.ai/settings ; pour les utilisateurs de la console (Console), s'assurer de disposer du rôle Claude Code ou Developer
Erreur Invalid API key	Clé d'API refusée	Vérifier la syntaxe et s'assurer que la clé n'a pas été révoquée dans la Console ; exécuter env | grep ANTHROPIC pour détecter un éventuel fichier .env chargeant une clé obsolète

L'erreur liée à la précision de l'horloge système en cas de connexions répétées est souvent omise — sur une machine virtuelle isolée du réseau, l'horloge peut présenter un décalage de plusieurs jours, invalidant immédiatement les tokens émis. Une simple mise à l'heure résout l'anomalie.

💡 En résumé : En cas d'erreur de connexion, commencez par vérifier les identifiants actifs avec /status ; le piège classique réside dans une variable ANTHROPIC_API_KEY résiduelle dans la configuration shell court-circuitant l'abonnement (exécuter unset et nettoyer la configuration) ; les déconnexions systématiques proviennent souvent de l'horloge système ou du trousseau d'accès macOS (Keychain).

---

04 Configuration : paramètres, hooks ou serveurs MCP inactifs

La deuxième catégorie concerne les paramètres inactifs — vous configurez des règles, des hooks ou des serveurs MCP dans settings.json, mais Claude semble les ignorer. La documentation officielle y consacre une page intitulée « Déboguer votre configuration », dont le principe clé est simple : vérifiez ce que Claude Code a réellement chargé, plutôt que de supposer la bonne prise en compte de vos modifications.

Analogie : Déposer un devoir ne garantit pas sa réception par l'enseignant. Vous l'avez laissé sur le bureau, mais il a pu être déplacé, glissé dans le cahier d'un autre élève, ou remplacé par une version ultérieure. Pour la configuration, le principe est identique — vérifiez quel fichier est lu par l'application, plutôt que de modifier sans cesse la version que vous croyez correcte.

Outils de diagnostic pour identifier le contenu chargé

Voici la boîte à outils dédiée à la configuration, à utiliser selon vos besoins :

Commande	Objectif du contrôle
/context	Répartition de l'usage de la fenêtre de contexte (prompts système, fichiers en mémoire, skills, outils MCP, historique)
/memory	Fichiers CLAUDE.md et fichiers de règles chargés
/skills	Skills configurés et disponibles (projet, utilisateur, plugins)
/agents	Configuration et paramètres des sous-agents
/hooks	Liste des hooks enregistrés dans la session active
/mcp	Liste et statut des serveurs MCP connectés
/permissions	Règles de permissions d'autorisation et de refus actives
/debug [description]	Activer les logs de débogage pour la session active et inviter Claude à utiliser les logs et les chemins pour diagnostiquer
/status	Sources de configuration actives (y compris l'usage de la configuration managée)

La méthode consiste à utiliser la commande dédiée pour vérifier que vos modifications figurent bien dans la liste. Par exemple, si un hook ne s'exécute pas, lancez /hooks pour vérifier son enregistrement — s'il n'y apparaît pas, le fichier n'a pas été lu ; s'il apparaît mais ne s'exécute pas, l'anomalie se situe au niveau du filtre de correspondance (matcher).

Les pièges de configuration fréquents chez les débutants

Voici une sélection des erreurs les plus fréquentes issues du guide officiel :

Symptôme	Cause probable	Résolution
Le hook ne s'exécute pas	Le filtre matcher est rédigé en minuscules (ex. "bash")	Les noms d'outils respectent la casse et commencent par une majuscule : Bash, Edit, Write, Read
Le hook ne s'exécute pas	Le hook a été écrit dans un fichier externe distinct	Les hooks utilisateur ou projet doivent obligatoirement figurer sous la clé "hooks" dans settings.json
Les valeurs de settings.json semblent ignorées	La même clé est définie dans settings.local.json	Le fichier settings.local.json surcharge settings.json, et tous deux surchargent ~/.claude/settings.json (voir chapitre 31)
Le serveur MCP de .mcp.json ne charge pas	Le fichier a été placé dans le sous-dossier .claude/	La configuration MCP du projet doit être placée à la racine du dépôt dans .mcp.json, et non dans le dossier .claude/
Le serveur MCP du projet n'apparaît pas	La confirmation d'approbation initiale a été désactivée	Les serveurs définis au niveau projet exigent une approbation, exécuter /mcp pour la valider (voir chapitre 22)
Les consignes du fichier CLAUDE.md d'un sous-dossier sont inactives	Le chargement s'effectue « à la demande »	Ce fichier n'est chargé que lorsque Claude utilise l'outil Read pour accéder à ce sous-dossier, et non au démarrage de la session (voir chapitre 18)

L'erreur sur la casse du filtre de hook (matcher) est très classique : définir un hook PostToolUse avec le filtre "edit|write" n'exécutera aucune action lors des modifications de fichiers. La commande /hooks indique pourtant la bonne prise en compte du filtre, et la configuration semble correcte — la cause réside dans l'absence de majuscules aux noms d'outils, qui doivent être formulés "Edit|Write". La documentation officielle le précise : « la correspondance respecte la casse. » C'est le genre de détail bloquant facile à corriger une fois identifié.

Permissions : « pourquoi la règle configurée est-elle ignorée ou donne-t-elle lieu à une alerte ? »

Les anomalies de permissions s'apparentent aux problèmes de configuration, et se déclinent sous deux formes fréquentes :

1. La consigne formulée dans CLAUDE.md est ignorée. Règle essentielle : inscrire « ne modifie jamais .env » dans CLAUDE.md constitue une directive (soft), pas une garantie d'exécution. La documentation l'explicite clairement : CLAUDE.md sert à orienter les choix de Claude. Pour imposer des limites strictes et incontournables (hard), vous devez configurer des règles de permissions ou des hooks (voir chapitres 20 et 21). Pour interdire fermement une action, ne comptez pas sur CLAUDE.md, configurez une règle deny ou un hook PreToolUse.

2. La règle deny n'intercepte pas les commandes équivalentes. Si vous définissez la règle rm * pour interdire les suppressions, Claude peut toujours utiliser /bin/rm ou find . -delete. La cause : les filtres de préfixes analysent la syntaxe exacte de la commande, pas l'appel système sous-jacent. Pour y remédier, vous devez déclarer chaque variante, ou implémenter un hook PreToolUse ou un environnement isolé (sandbox). Lors de vos diagnostics, commencez par lancer /permissions pour analyser les règles d'autorisation et de refus actives.

这背后是第 50 篇反模式讲过的同一个道理：把「安全边界」托付给一句自然语言指令，本身就是个反模式——指令是软的，规则和 hook 才是硬的。

💡 En résumé : Si un paramètre est ignoré, utilisez la suite de commandes /context, /memory, /hooks, /mcp, /permissions pour contrôler le contenu chargé ; les erreurs classiques proviennent de la casse du filtre de hook (matcher), d'une surcharge par settings.local.json, d'un mauvais emplacement pour .mcp.json ou d'consignes de sécurité rédigées dans CLAUDE.md au lieu de règles deny.

---

05 Performances : lenteurs, consommation mémoire ou fichiers non trouvés

La troisième catégorie concerne les baisses de performances — temps de réponse allongés, consommation mémoire excessive, autocomplétion @file inopérante. Ces points sont traités officiellement sous l'intitulé « Performances et stabilité », et découlent généralement d'un contexte saturé ou de détails de configuration locale, rarement de bugs de l'application.

Analogie : Un ordinateur qui ralentit est souvent encombré d'applications actives en arrière-plan, ce n'est pas une panne matérielle. Avant de l'envoyer en réparation, vous commencez par vider les programmes énergivores et vider le cache. Pour Claude Code, appliquez le même principe — allégez l'espace de contexte avant d'envisager une réinstallation.

Lenteurs et mémoire : alléger l'espace de contexte

La documentation officielle propose une démarche pragmatique :

1. Utilisez régulièrement /compact pour compresser le contexte (synthétiser les échanges, voir chapitre 19).
2. Redémarrez Claude Code entre deux tâches d'envergure.
3. Ajoutez les répertoires de build ou de dépendances volumineux dans votre fichier .gitignore pour éviter qu'ils ne soient scannés.

Si la consommation mémoire persiste, exécutez /heapdump — cette commande génère un instantané de la mémoire (heap dump JavaScript) sur votre bureau ~/Desktop (ou dans votre répertoire personnel sous Linux) ; vous pourrez joindre ce fichier lors de l'ouverture d'une issue GitHub dédiée à une anomalie mémoire. C'est un outil à connaître pour les cas d'assistance avancée.

关于「卡死、转圈不动」：官方说得很干脆——先按 Ctrl+C 试着取消当前操作；要是彻底没反应，关掉终端重启。重启不会丢对话，在同一目录跑 claude --resume 就能接着上次的会话往下走。

Les boucles de compression (Thrashing) : une alerte impressionnante

Il peut arriver que le message suivant s'affiche : Autocompact is thrashing: the context refilled to the limit.... Pas d'inquiétude — cela signifie que la compression automatique a fonctionné, mais que l'ouverture d'un fichier très lourd ou le retour d'une commande a immédiatement saturé le contexte à nouveau. Pour éviter de consommer inutilement des appels d'API, Claude Code interrompt le processus. Pour y remédier : demandez de lire le fichier volumineux par blocs (en ciblant des lignes ou une fonction précise au lieu d'ouvrir tout le fichier), utilisez /compact avec la consigne « conserve uniquement le plan et le diff », ou faites table rase avec /clear.

Autocompation @file ou recherche inopérante : utiliser le ripgrep du système

Si la recherche de fichiers, l'autocomplétion avec @file ou les skills personnalisés ne trouvent aucun document, il est probable que la version intégrée de ripgrep (l'outil de recherche rapide) rencontre une incompatibilité avec votre système. La solution officielle consiste à installer la version système de ripgrep et à configurer Claude Code pour qu'il l'utilise :

# macOS
brew install ripgrep

Puis déclarez la variable d'environnement USE_BUILTIN_RIPGREP=0 (la configuration des variables d'environnement est abordée au chapitre 42).

Voici un guide d'orientation rapide pour les problèmes de performances :

Symptôme constaté	Action recommandée
Lenteurs progressives ou mémoire élevée	Exécuter /compact, puis redémarrer Claude Code
Blocage complet ou attente infinie	Ctrl+C ; en cas d'échec, fermer le terminal et exécuter claude --resume
Message Autocompact is thrashing	Diviser la lecture des fichiers lourds et lancer /compact
Autocomplétion @file ou recherche inopérante	Installer ripgrep sur le système et déclarer USE_BUILTIN_RIPGREP=0
Caractères corrompus dans le terminal intégré	Exécuter /terminal-setup au sein de Claude pour désactiver le rendu GPU

L'anomalie liée aux caractères corrompus survient parfois dans le terminal intégré de VS Code, les lettres étant remplacées par des carrés illisibles. Lancez la commande /terminal-setup pour désactiver l'accélération matérielle (GPU) du terminal, puis rechargez la fenêtre pour rétablir l'affichage — il s'agit d'un problème de rendu graphique local indépendant de Claude.

💡 En résumé : Face à un problème de performances, commencez par alléger le contexte — la suite /compact et redémarrage résout la majorité des cas ; interrompez les blocages avec Ctrl+C ou claude --resume ; utilisez la version système de ripgrep en cas d'échec de recherche ; corrigez les problèmes d'affichage du terminal avec /terminal-setup.

---

06 Erreurs d'API : face à un message d'erreur, déterminez si la cause vous est imputable

La quatrième catégorie concerne les messages de type API Error: ... affichés dans la console. Les débutants s'en inquiètent souvent, mais la première étape consiste à identifier si la cause se situe côté serveur ou de votre côté — les résolutions étant opposées.

Note préalable : Claude Code intègre un mécanisme de reconnexion automatique

Le fonctionnement sous-jacent est important à connaître : en cas d'erreur de serveur, de surcharge, de timeout, de limitation de débit ou de déconnexion temporaire, Claude Code tente automatiquement de se reconnecter jusqu'à 10 fois avec un délai exponentiel (backoff). Un compte à rebours s'affiche dans la console : Retrying in Ns · attempt x/y. L'affichage final d'un message d'erreur signifie donc que ces 10 tentatives automatiques ont échoué.

Trois types d'erreurs, trois résolutions

Voici une synthèse des erreurs d'API classée en trois typologies de diagnostic :

Message d'erreur	Responsabilité	Résolution
API Error: 500 / 529 Overloaded / Server is temporarily limiting requests	Serveur (indépendant de votre fait)	Patienter avant de réessayer ; consulter status.claude.com ; utiliser /model pour basculer vers un autre modèle (la capacité étant allouée par modèle)
You've hit your session/weekly/Opus limit	Votre quota est consommé	Attendre la réinitialisation ; exécuter /usage pour analyser vos crédits ; utiliser /usage-credits pour acquérir du crédit ou faire évoluer votre formule
Prompt is too long / Request too large	Votre prompt est trop volumineux	Exécuter /compact ou /clear ; cibler des portions de lignes pour les fichiers volumineux au lieu de les insérer en entier

Les approches de résolution de ces trois typologies sont fondamentalement différentes : attendre pour la première, recharger ses crédits ou patienter pour la seconde, et optimiser le contexte pour la troisième. Se méprendre sur la cause conduit à des actions inadaptées (comme réinitialiser sa session alors que les serveurs sont indisponibles, ou s'obstiner à relancer une requête sur un compte sans crédits).

Une autre anomalie concerne l'impossibilité d'établir la connexion avec l'API (Unable to connect to API, fetch failed, Request timed out accompagné d'alertes réseau) — la cause réside généralement dans votre configuration locale de réseau (proxy, pare-feu, VPN) et non chez Anthropic. Commencez par vérifier l'accessibilité de l'hôte de l'API depuis votre terminal :

curl -I https://api.anthropic.com

Si la commande réussit, le réseau fonctionne et l'anomalie se situe au niveau applicatif (configuration de proxy ou de certificats). Si elle affiche Could not resolve host ou échoue en timeout, la connexion est bloquée. Sur les réseaux d'entreprise, vous devez configurer la variable HTTPS_PROXY. En cas de déconnexions fréquentes sur réseau instable, vous pouvez allonger la durée limite de requête via les deux variables d'environnement suivantes (leur configuration est abordée au chapitre 42) :

Variable d'environnement	Valeur par défaut	Description
API_TIMEOUT_MS	600000 (10 minutes)	Timeout d'une requête individuelle, à augmenter sur réseau lent ou via proxy
CLAUDE_CODE_MAX_RETRIES	10	Nombre de tentatives de reconnexion automatique, à réduire dans les scripts pour accélérer la remontée d'erreurs

Deux messages d'erreur fréquents et mal interprétés

1. model not found / you may not have access to it : le nom du modèle déclaré dans votre configuration n'est pas reconnu ou votre compte ne dispose pas des droits d'accès. Utilisez /model au sein de la CLI interactive pour sélectionner un modèle disponible. Si un modèle obsolète réapparaît systématiquement, vérifiez l'origine de sa configuration selon la hiérarchie suivante : option --model → variable d'environnement ANTHROPIC_MODEL → settings.local.json → clés model des fichiers settings.json successifs, et supprimez la valeur obsolète pour rétablir le choix par défaut de votre compte. La documentation recommande d'utiliser les alias de modèles (sonnet, opus) plutôt que les identifiants de versions figés, les alias ciblant automatiquement la version stable la plus récente (voir chapitre 04 pour la configuration de /model ou de ANTHROPIC_MODEL).

2. Claude Code is unable to respond to this request, which appears to violate our Usage Policy : la requête a été bloquée par le contrôle de conformité de la charte d'utilisation. Notez un aspect contre-intuitif : le contrôle évalue l'intégralité de l'historique de la session, et pas uniquement le dernier message. Reformuler la dernière consigne au sein de la même session provoquera donc probablement le même rejet. La bonne approche consiste à annuler la dernière étape avec /rewind ou un double appui sur Esc (voir chapitre 37) pour reformuler différemment ou changer d'approche ; si la cause reste indéterminée, lancez /clear pour ouvrir une session vierge.

💡 En résumé : Les erreurs d'API relèvent de trois catégories — les codes 5xx/529 proviennent du serveur (patienter, vérifier la page de statut ou changer de modèle), le message hit your quota limit signale la consommation de vos crédits (attendre ou recharger), et l'alerte too long/too large indique un prompt trop lourd (/compact ou lecture par blocs) ; l'échec de connexion Unable to connect provient de votre réseau local (tester avec curl, configurer un proxy si nécessaire) ; utilisez les alias de modèles et supprimez les identifiants obsolètes.

---

07 Outils avancés : logs de débogage --debug et comparaison avec une configuration vierge

Les six catégories précédentes couvrent la majorité des cas. Face à des comportements inexpliqués ou non documentés, vous pouvez recourir à deux outils avancés pour identifier l'anomalie.

Analogie : L'usage du multimètre et du test de déconnexion pour dépanner un circuit électrique. Face à une panne complexe, un technicien utilise un multimètre pour mesurer les tensions en direct (consulter les logs en temps réel) ou déconnecte les appareils un à un pour isoler l'élément défectueux (isoler les variables). Les deux méthodes avancées de Claude Code reposent sur ce principe.

Outil 1 : option --debug pour analyser l'exécution en temps réel

Si le résultat ne fournit pas d'explication, démarrez l'application avec l'option --debug pour afficher l'historique d'exécution. Vous pouvez associer des options secondaires pour cibler le composant à analyser :

Commande	Cas d'usage ciblé
claude --debug	Logs de débogage généraux pour analyser le flux global
claude --debug mcp	Sortie stderr du démarrage et de la connexion des serveurs MCP (utile si le serveur apparaît connecté mais ne liste aucun outil)
claude --debug hooks	Analyse des événements de hooks, des filtres associés, des codes de retour et des sorties (utile si un hook ne s'exécute pas)

Vous disposez également de la commande interne /debug [description] qui active le débogage pour la session active et invite Claude à s'appuyer sur les logs et les fichiers pour vous assister.

Exemple concret : un hook listé dans /hooks ne s'exécute pas. Démarrez avec claude --debug hooks and déclenchez l'action correspondante. Les logs afficheront précisément le cheminement : « détection de l'événement, évaluation de tel filtre, statut de correspondance ». C'est bien plus efficace que d'analyser visuellement le fichier de configuration.

Outil 2 : comparaison avec une configuration vierge

C'est une méthode d'isolement précieuse pour déterminer si l'anomalie provient de vos propres paramètres. Le principe consiste à démarrer une session sans charger aucun paramètre local et à la comparer au comportement habituel — si l'anomalie disparaît, la cause réside dans votre configuration. La commande officielle :

cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

Cette commande déclare la variable CLAUDE_CONFIG_DIR vers un répertoire vide, ignorant l'intégralité du contenu de ~/.claude ; elle démarre par ailleurs l'application depuis un répertoire temporaire exempt de sous-dossier .claude, de fichier .mcp.json ou de CLAUDE.md, ignorant également les paramètres de projet. La session démarre ainsi sans aucune configuration utilisateur ou projet, sans hooks, sans serveurs MCP, sans plugins et sans historique.

• L'anomalie disparaît dans la session vierge → La cause réside dans votre configuration locale ~/.claude ou dans celle du projet. Ajoutez de nouveau vos configurations une à une (en déplaçant un fichier à la fois ou en démarrant depuis le répertoire projet) jusqu'à ce que l'anomalie réapparaisse, isolant ainsi l'élément défectueux.
• L'anomalie persiste au sein de la session vierge → La cause se situe en dehors de vos configurations locales (paramètres managés de votre organisation, variables d'environnement globales, ou problème lié à l'installation).

这套「二分法」是排查的通用智慧——通过「砍掉一半变量看问题在不在」来缩小范围。比如 Claude 莫名其妙不读某条 CLAUDE.md 规则，靠干净会话就能确认「不是 Claude Code 的 bug，是项目里两份 CLAUDE.md 指令打架」，省了去翻一晚上文档。

💡 En résumé : Pour les anomalies complexes, recourez à deux méthodes avancées — claude --debug [mcp/hooks] pour analyser le flux en temps réel et identifier le composant en échec, et la comparaison avec une configuration vierge (en orientant CLAUDE_CONFIG_DIR vers un dossier vide) pour déterminer si vos paramètres locaux sont en cause, avant de les réactiver un à un.

---

08 Pratique : réaliser le bilan de santé de votre installation

La théorie doit s'accompagner d'exercice. Nous vous guidons pour exécuter le bilan de santé /doctor et vérifier vos identifiants actifs. Cette manipulation ne requiert aucun projet complexe, l'installation de Claude Code suffit.

Étape 1 : Vérifier la validité de l'installation et sa version dans le terminal

claude --version

Résultat attendu : Affichage de la version de l'application, par exemple 2.1.xxx (Claude Code). L'affichage du numéro de version valide l'installation. Si le terminal retourne command not found: claude, le chemin de l'exécutable ne figure pas dans la variable PATH — c'est un problème d'installation, reportez-vous au chapitre 02 pour le configurer (l'emplacement par défaut sous macOS/Linux étant ~/.local/bin).

Étape 2 : Lancer l'application et exécuter le diagnostic

claude

Saisissez au sein de la session :

/doctor

Résultat attendu : Affichage d'un panneau de diagnostic listant l'état de l'installation, la validité de la configuration (les erreurs de schéma ou clés incorrectes apparaissant en rouge), le statut MCP et l'état du contexte. L'absence d'erreurs confirme la validité de vos paramètres. Si une anomalie est signalée, appuyez sur f pour soumettre le rapport à Claude et le laisser vous guider.

Étape 3 : Identifier les identifiants actifs

Saisissez ensuite :

/status

Résultat attendu : Affichage de la méthode d'authentification active. Si vous disposez d'un abonnement, la mention OAuth doit apparaître à l'exclusion de toute clé API. Si une clé API est mentionnée par erreur, vous venez d'identifier l'anomalie décrite en introduction : nettoyez vos fichiers de configuration shell pour exécuter unset ANTHROPIC_API_KEY et supprimer la déclaration.

Étape 4 (optionnelle) : Démarrer une session avec configuration vierge

Pour mettre en pratique la méthode d'isolement de la section 07, lancez une session vierge :

cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

Résultat attendu : La session s'exécute sans charger aucun de vos fichiers CLAUDE.md, serveurs MCP ou paramètres utilisateur habituels (les commandes /memory ou /mcp s'avèrent vides). C'est votre base de comparaison pour isoler les anomalies liées à votre configuration. Note : sous Linux et Windows, l'application demandera de vous reconnecter (les identifiants étant stockés dans le répertoire de configuration), tandis que sous macOS, les jetons enregistrés dans le trousseau Keychain seront réutilisés automatiquement. Quittez la session une fois le test terminé, ce répertoire temporaire n'affecte pas votre configuration réelle.

Ces quatre étapes résument la démarche de diagnostic de base : bilan de santé, contrôle des identifiants et session vierge. En cas de dysfonctionnement, suivez cette séquence méthodologique plutôt que de procéder par essais successifs.

💡 En résumé : Pratiquez la séquence complète claude --version → /doctor → /status → session vierge ; gardez en tête que /doctor cible l'anomalie et /status identifie les identifiants actifs, résolvant la majorité des cas fréquents.

---

09 Résumé

Ce chapitre a mis en place une méthode de diagnostic structurée — de la catégorisation initiale des symptômes au choix des commandes, jusqu'aux outils avancés.

Synthèse de la démarche :

Situation	Action de diagnostic	Point clé
Incertitude sur la nature de l'anomalie	Analyser le tableau d'orientation + exécuter /doctor	Catégoriser d'abord, agir ensuite sans tâtonner
Reconnexions répétées ou organisation bloquée	Consulter les identifiants avec /status	Fréquemment lié à une variable ANTHROPIC_API_KEY résiduelle court-circuitant l'abonnement
Paramètres, hooks ou serveurs MCP inactifs	Vérifier le contenu chargé avec /context, /hooks, /mcp	Valider les fichiers réellement lus ; attention à la casse et aux surcharges
Lenteurs, mémoire élevée ou recherche inefficace	Exécuter /compact et redémarrer / installer ripgrep	Souvent lié à la saturation du contexte ou à la configuration système
Message API Error affiché	Déterminer s'il s'agit du serveur, de vos crédits ou du prompt	Code 5xx (vérifier status.claude.com), limitation (crédits), ou prompt trop lourd (optimiser)
Anomalie complexe non identifiée	Démarrer avec --debug ou comparer avec une session vierge	Analyser les logs en temps réel et isoler les variables de configuration

Vous devriez maintenant être en mesure de : aborder sereinement les anomalies de Claude Code — catégoriser le problème à l'aide du tableau d'orientation, utiliser /doctor pour le bilan de santé et /status pour contrôler les identifiants ; appliquer les résolutions correspondantes (installation, authentification, configuration, performances, API) ; recourir aux logs --debug ou à une session vierge en cas de difficulté persistante ; et enfin utiliser /feedback pour signaler le problème. L'assimilation de cette méthode vous permettra de diagnostiquer efficacement chaque message d'erreur.

De l'installation à la personnalisation, en passant par la résolution des problèmes, vous avez désormais parcouru l'intégralité du processus pratique. Il ne reste plus qu'à stabiliser le vocabulaire technique rencontré.

Le chapitre suivant 52 « Glossaire (accessible aux débutants) » — tout au long de cette série, de nombreux termes ont été abordés : CLAUDE.md, fenêtre de contexte, MCP, subagents, hooks, points de contrôle, compression automatique... Le prochain chapitre vous propose un glossaire vulgarisé : chaque terme est explicité simplement et illustré par une analogie parlante, le tout classé par thématiques pour une consultation aisée. À ce propos : si l'on vous interrogeait sur le lien entre tokens et fenêtre de contexte, sauriez-vous l'expliquer simplement en une phrase ?

---

Lectures recommandées

• Commandes obliques (Slash Commands) : appeler les raccourcis de Claude avec un simple /
• Configuration de développement : optimiser l'environnement de travail de Claude
• Quatre tâches courantes : exploration de la base de code, correction de bugs, refactorisation et écriture de tests