Sommaire
- 1. Les « commandes de diagnostic » à lancer en premier
- 2. Authentification et connexion
- 3. Usage et limites de débit (le plus fréquent)
- 4. Contexte et tokens
- 5. Serveur et modèle
- 6. Installation, PATH et mise à jour
- 7. Réseau et proxy
- 8. MCP (serveurs connectés)
- 9. Permissions et outils
- 10. Autres (thinking / image-PDF / IDE)
- 11. Aide-mémoire erreur → correctif
- Conclusion
- FAQ
Vous travaillez dans Claude Code et il s'arrête brusquement sur une erreur — « reconnectez-vous », « limite de débit », « prompt trop long », « MCP ne se connecte pas ». Il y en a tellement de sortes que chercher chacune sur Google devient fastidieux. Cet article est une référence pratique qui répertorie les erreurs que vous rencontrerez couramment dans Claude Code, avec la cause et la commande à lancer pour chacune.
L'essentiel d'abord : pour la plupart des erreurs, lancer d'abord claude doctor (diagnostic complet), /status (votre authentification actuelle) et /context (répartition du contexte) permettra de cerner la cause. Et les cas fréquents se regroupent en quatre familles : ① usage/limites de débit, ② débordement de contexte, ③ authentification expirée, ④ échecs de connexion MCP. Ci-dessous, chaque catégorie est organisée selon « symptôme → cause → commande de correction ». Mettez-le en favori et sautez à la section pertinente quand vous êtes bloqué.
En cas de doute, ces 3 commandes
— la plupart des erreurs commencent par isoler la cause
Les quatre familles : ① usage/limites de débit ② débordement de contexte ③ authentification expirée ④ échec de connexion MCP.
Et discrètement, « mettre à jour vers la dernière version » claude update résout beaucoup de bugs.
* Les commandes et correctifs présentés ici s'appuient sur la documentation officielle de Claude Code (à jour en 2026). Claude Code évolue vite, et les noms de commandes comme la formulation des messages peuvent changer. Vérifiez la dernière version avec claude doctor et la documentation officielle.
1. Les « commandes de diagnostic » à lancer en premier
Avant de plonger dans les erreurs spécifiques, connaître les commandes de diagnostic qui aident à isoler la cause vous permet de cerner rapidement la plupart des problèmes.
| Commande | Ce qu'elle affiche / fait |
|---|---|
claude doctor | Vérification complète de l'installation, des réglages, des serveurs MCP, de l'usage du contexte |
/status | La méthode d'authentification actuellement active (Pro / Max / Team / clé API) |
/context | Répartition du contexte (prompt système, historique, fichiers, outils MCP) |
/usage | Limites du forfait actuel et heures de réinitialisation |
/permissions | Liste des règles de permission (allow/deny) et leurs sources |
/mcp | État de connexion des serveurs MCP et nombre d'outils exposés |
/feedback | Signaler un bug à Anthropic avec le journal de conversation |
2. Authentification et connexion
La famille « ça marchait et soudain on me demande de me reconnecter ». Le piège classique : une clé API en variable d'environnement qui prend le pas sur votre abonnement.
| Symptôme | Cause | Correctif |
|---|---|---|
| Not logged in · Please run /login | Aucun identifiant disponible pour cette session (une connexion enregistrée qui n'a pas pu être renouvelée affiche Login expired · Please run /login) | /login. Si cela se répète, vérifiez l'horloge système et le verrouillage du trousseau |
| Invalid API key · Fix external API key | L'API a rejeté une clé issue de ANTHROPIC_API_KEY ou d'apiKeyHelper (souvent une clé obsolète) | env | grep ANTHROPIC → unset ANTHROPIC_API_KEY → /login |
| OAuth token revoked · Please run /login Please run /login · API Error: 401 OAuth token has expired ... | Déconnecté partout / un admin a retiré l'accès (revoked) ; échec du rafraîchissement auto. (expired) | /login. Si cela revient dans la même session, /logout → /login. Si cela arrive à chaque lancement, soupçonnez l'horloge |
| Your ANTHROPIC_API_KEY belongs to a disabled organization · … API Error: 400 ... This organization has been disabled. | Une vieille ANTHROPIC_API_KEY d'une organisation désactivée est utilisée. Sans variable d'environnement, c'est l'organisation de votre /login qui est désactivée | Retirez la clé du profil du shell (.zshrc etc.) → /login → confirmez avec /status. Sans variable d'environnement, contactez le support ou connectez-vous avec un autre compte |
| 403 Forbidden (after login) | Abonnement expiré / rôle manquant / interférence d'un proxy | Vérifiez l'abonnement et le rôle dans la Console. Pour les proxies, définissez HTTPS_PROXY |
Règle générale : une clé API en variable d'environnement a priorité sur la connexion par abonnement. Si vous avez défini ANTHROPIC_API_KEY pour une tâche CI et l'avez oubliée, votre forfait personnel Pro/Max est ignoré. Vérifier « quelle identification est active » avec /status en premier est le bon réflexe. Pour un approfondissement des correctifs d'authentification et de connexion (la priorité de ANTHROPIC_API_KEY, l'expiration du token, le Keychain, etc.), voir les causes et solutions des erreurs d'authentification et de connexion.
3. Usage et limites de débit (le plus fréquent)
La plainte la plus fréquente avec Claude Code. D'après le guide officiel des coûts (Manage costs effectively), chaque tour de Claude Code transporte le contenu de fichiers, des appels d'outils et un raisonnement en plusieurs étapes, si bien qu'une seule session de débogage peut consommer plus qu'une journée de chat. C'est pourquoi vous atteignez les limites plus vite qu'il n'y paraît.
3 actions quand vous « atteignez la limite »
/usage pour les limites et l'heure de réinitialisation, /status pour l'identification/model pour un modèle plus léger, /compact pour réduire l'historique, désactiver les MCP inutilisés
À noter : « Server is temporarily limiting requests » est un bridage côté serveur de courte durée, pas la limite de votre forfait. Attendez simplement et réessayez.
Ne le confondez pas avec les limites de forfait (session/hebdomadaire).
Pour aller plus loin : « API Error: Request rejected (429) » signifie que vous avez atteint la limite de débit de votre clé API (ou de votre projet Amazon Bedrock / Google Cloud) ; si vous pensiez utiliser un abonnement, vérifiez dans /status qu'aucune ANTHROPIC_API_KEY ne traîne. « Credit balance is too low » signifie que le solde prépayé de la Console est épuisé, ou que les requêtes partent avec une clé API de la Console alors que vous vouliez utiliser l'abonnement (rechargez, ou vérifiez la clé dans /status et retirez-la). À noter : en mars 2026, des utilisateurs Pro et Max se sont plaints que leurs limites Claude Code s'épuisaient bien plus vite que prévu, et Anthropic a reconnu enquêter en priorité absolue (The Register, 31 mars 2026). Si cela se reproduit, mettez à jour vers la dernière version, mesurez avec /usage, et utilisez /feedback au besoin. Pour économiser systématiquement des tokens, voir l'économie de tokens IA et l'économie de tokens dans Claude Code. Pour le fonctionnement de « usage limit reached » (la fenêtre de 5 heures et la fenêtre hebdomadaire) et la marche à suivre une fois le plafond atteint, voir en détail l'article dédié à usage limit reached.
4. Contexte et tokens
Cela survient lorsque vous traitez de longues réunions ou des fichiers énormes.
| Symptôme | Cause | Correctif |
|---|---|---|
| Prompt is too long | La conversation + les fichiers dépassent la fenêtre de contexte | /compact (résumer), /clear (réinitialiser), /context pour voir la répartition, désactiver les MCP inutilisés via /mcp |
| Error during compaction: Conversation too long | Pas assez d'espace libre pour la sortie de la compaction | Échap deux fois pour remonter de quelques tours, puis /compact. Si toujours bloqué, /clear |
| Autocompact is thrashing | Une sortie énorme remplit à nouveau le contexte juste après la compaction | Lire les gros fichiers par plage de lignes / /compact keep only <focus> / déléguer à un sous-agent |
L'astuce est de ne jamais lire un fichier énorme en entier. Passez les journaux et les données en petits morceaux par plage de lignes. Bien saisir la notion de fenêtre de contexte rend cette catégorie d'erreur bien plus rare. Pour les causes détaillées et les solutions de l'erreur Prompt is too long (la fenêtre de 200K contre 1M, l'usage des sous-agents), voyez l'article dédié.
5. Serveur et modèle
| Symptôme | Cause | Correctif |
|---|---|---|
| 500 Internal server error | Panne temporaire côté Anthropic | Consultez status.claude.com → réessayez après 1 min |
| 529 Overloaded (repeated) | API temporairement à pleine capacité | Attendez quelques minutes. Changez de modèle avec /model pour répartir la charge |
| Request timed out | Aucune réponse dans le délai par défaut de 10 min | Découpez la tâche. Sur une ligne lente, augmentez API_TIMEOUT_MS |
| There's an issue with the selected model / Model '…' not found | Nom de modèle erroné ou non inclus dans votre forfait | /model pour resélectionner. Vérifiez une variable ANTHROPIC_MODEL obsolète |
| Claude Opus is not available with the Claude Pro plan | Modèle sélectionné absent de votre forfait | /model vers un modèle disponible. Après un changement de forfait, /logout→/login |
Pourquoi 529 Overloaded / 500 relèvent du serveur et ne consomment pas votre quota, comment fonctionne la nouvelle tentative automatique (jusqu'à 10 fois) et en quoi cela diffère du 429, voir 529 Overloaded / 500 : causes et solutions.
6. Installation, PATH et mise à jour
| Symptôme | Cause | Correctif |
|---|---|---|
| command not found: claude | Le répertoire d'installation n'est pas dans le PATH | Ajoutez ~/.local/bin (Win : %USERPROFILE%\.local\bin) au PATH |
| Install fails (HTML error, etc.) | Proxy / blocage régional | Homebrew brew install --cask claude-code / WinGet winget install Anthropic.ClaudeCode |
| TLS / SSL certificate verification failed | Inspection TLS du proxy d'entreprise / CA manquante | Pointez NODE_EXTRA_CA_CERTS=/path/ca.pem. NE DÉFINISSEZ JAMAIS NODE_TLS_REJECT_UNAUTHORIZED=0 |
| Plusieurs installations de Claude Code (versions discordantes, comportement inattendu) | Doublons entre native, npm, Homebrew, WinGet, etc. | Vérifiez avec which -a claude (Windows : where.exe claude) et gardez-en une ; l'installation native dans ~/.local/bin/claude est recommandée. P. ex. npm uninstall -g @anthropic-ai/claude-code |
| Bugs from an old version | Pas à jour | claude update (le correctif n°1 qui résout beaucoup de bugs) |
| L'application de bureau affiche « Impossible d'ouvrir cette application » | Le paquet MSIX a été enregistré à moitié lors d'une mise à jour (Windows) | Fermez les processus résidents, puis Réparer dans les paramètres. explication détaillée |
Les causes et solutions de command not found: claude (PATH, conflits entre plusieurs installations, permissions npm, le piège du mauvais shell sous Windows) sont détaillées dans comment corriger l'erreur "command not found" d'installation et de PATH.
7. Réseau et proxy
Fréquent sur les réseaux d'entreprise et les VPN. Confirmez d'abord la joignabilité avec curl -I https://api.anthropic.com.
| Symptôme | Cause | Correctif |
|---|---|---|
| Unable to connect to API / Connection refused … (ECONNREFUSED) | Hors ligne / blocage VPN / proxy non configuré | Définissez HTTPS_PROXY=http://proxy:8080. Demandez à la DSI d'autoriser api.anthropic.com |
| SSL certificate verification failed (corporate) | Certificat d'interception auto-signé | Obtenez le bundle CA auprès de la DSI et définissez NODE_EXTRA_CA_CERTS |
| 403 host_not_allowed (cloud runs) | En dehors de la liste d'autorisation de l'environnement cloud | Réglez l'accès réseau sur Custom et autorisez le domaine cible |
| Connection lost mid-response (avant la v2.1.227 : Connection closed mid-response) | Connecté et le flux avait démarré, puis la connexion a été coupée | La sortie partielle est conservée : répondez continue. Si cela se répète, vérifiez claude --version et mettez à jour |
Pour une analyse approfondie de la configuration du proxy, des certificats TLS (NODE_EXTRA_CA_CERTS), des domaines de l'allowlist et des raisons pour lesquelles NODE_TLS_REJECT_UNAUTHORIZED=0 est dangereux, voir causes et solutions des erreurs de connexion et de proxy. Connection lost mid-response (anciennement Connection closed mid-response) est un autre problème, postérieur à l'arrivée de la requête : causes et solutions quand la réponse est coupée en plein milieu détaille la démarche d'isolement et ce que chaque version a corrigé.
8. MCP (serveurs connectés)
Vous rencontrez ces erreurs dès que vous commencez à utiliser des serveurs MCP. Vérifiez d'abord l'état avec /mcp.
| Symptôme | Cause | Correctif |
|---|---|---|
| Server failed to connect / Pending approval | Serveur planté / injoignable / authentification requise | /mcp pour l'état. stdio : vérifiez que la commande existe et est exécutable ; HTTP : vérifiez l'URL/les en-têtes d'authentification |
| Tool not found | Connecté mais aucun outil exposé / mauvais nom | /mcp pour confirmer le nombre d'outils, claude mcp get <name> pour l'état de santé |
| Reconnection attempts exhausted | Serveur HTTP/SSE hors service après 5 tentatives | Confirmez que le serveur est actif, reconnexion manuelle dans /mcp. Pour stdio, redémarrez claude |
| MCP server timeout | Le démarrage ne se termine pas dans le délai MCP_TIMEOUT (30 s par défaut) | Augmentez-le en ms, par ex. MCP_TIMEOUT=60000 claude. Le "timeout" de .mcp.json est la limite d'exécution de chaque outil, pas l'attente au démarrage |
Pour un traitement détaillé selon l'état de la connexion MCP —failed, needs authentication ou pending— (y compris l'enveloppement de npx avec cmd /c sous Windows), voir comment corriger les erreurs de connexion MCP.
9. Permissions et outils
La famille « on m'a demandé une permission même en mode bypass ». Deux points clés : la documentation officielle liste les actions qui demandent encore une confirmation en mode bypass, et les règles deny bloquent dans tous les modes, bypass compris (les règles allow n'ont aucun effet en bypass ; voir Choose a permission mode dans la documentation officielle).
| Symptôme | Cause | Correctif |
|---|---|---|
| Asked for permission even in bypass mode | Les règles ask explicites, les outils qui exigent une interaction de l'utilisateur comme AskUserQuestion, et rm / rmdir sur un chemin critique comme la racine, votre dossier personnel ou le répertoire de travail (ce que la documentation appelle un circuit breaker) demandent toujours une confirmation en bypass. Les écritures dans des chemins protégés comme .git et .claude n'en demandent pas en bypass | Vérifiez et ajustez les règles ask dans /permissions. Les règles deny bloquent sans rien demander |
| Tool execution denied by PreToolUse hook | Un hook l'a bloqué avec le code de sortie 2 | Vérifiez le hook dans .claude/settings.json. Voyez la sortie avec claude --debug |
Pour comprendre pourquoi le bypass s'arrête quand même, voir pourquoi il demande une permission même en mode bypass ; pour une conception sûre des permissions, voir les modes de permission et la sécurité.
10. Autres (thinking / image-PDF / IDE)
- thinking blocks cannot be modified (400) : un bug connu où les blocs de raisonnement étendu sont corrompus dans l'historique. Échap deux fois → /rewind, sinon une nouvelle session, et
claude update. Détails : erreur 400 des blocs thinking. - court / une balise <invoke> brute s'affiche et l'outil ne s'exécute pas : un bug connu où la balise de contrôle de l'appel d'outil est générée corrompue. Si ça échoue deux fois, démarrez une nouvelle session (/clear). Détails : erreur de fuite de balise court / invoke expliquée.
- Could not check the pull request status : un problème de connexion à GitHub (souvent l'authentification
gh). Commencez pargh auth status. Détails : erreur d'état de PR. - Image was too large / PDF too large : les images de plus de 8000 px sur le grand côté (2000 px quand de nombreuses images sont dans le contexte), les PDF de plus de 100 pages / 20 Mo sont rejetés. Échap deux fois pour retirer la pièce jointe ; redimensionnez ou lisez par plage de lignes. Référencez les gros fichiers par chemin plutôt que de les coller.
- L'extension VS Code ne se connecte pas : confirmez que
claude --versionfonctionne dans le terminal de VS Code. Vérifiez le PATH, redémarrez VS Code, réinstallez l'extension.
11. Aide-mémoire erreur → correctif
| Quand cela arrive | Essayez d'abord ceci |
|---|---|
| Cause inconnue / général | claude doctor → /status → /context |
| Demande soudaine de connexion | /status → (si une clé obsolète) unset ANTHROPIC_API_KEY → /login |
| Limite de débit atteinte | /usage → /model plus léger → /compact → attendre |
| Prompt is too long | /compact → /clear → lire les gros fichiers par plage de lignes |
| 500/529/timeout | Consulter status.claude.com → attendre un peu → /model |
| command not found: claude | Ajouter ~/.local/bin au PATH |
| Connexion impossible (réseau d'entreprise) | curl -I https://api.anthropic.com → HTTPS_PROXY/NODE_EXTRA_CA_CERTS |
| MCP ne se connecte pas | /mcp → vérifier URL/permissions/commande → MCP_TIMEOUT |
| Demande de permission même en bypass | /permissions pour vérifier les règles ask (supprimer un chemin critique demande une confirmation même en bypass) |
| Juste envie que ça marche | claude update (la dernière version corrige beaucoup de choses) |
Conclusion
Claude Code génère beaucoup d'erreurs, mais le premier réflexe est d'isoler la cause avec trois commandes : claude doctor / /status / /context — cela débloque la plupart des problèmes. Les cas fréquents forment quatre familles — usage/limites de débit, débordement de contexte, authentification expirée, échec de connexion MCP — avec /usage, /compact, /login et /mcp comme correctifs de première ligne.
Et l'action la plus forte, facile à négliger, c'est de rester à jour avec claude update. Claude Code évolue vite, et les bugs passés (comme le 400 des blocs thinking) disparaissent souvent juste en montant de version. « En cas de blocage, les trois commandes de diagnostic d'abord ; si ce n'est pas réglé, mettez à jour vers la dernière version. » Gardez ce réflexe et vous cesserez de perdre du temps dans les erreurs.
Et si ce n'est pas une erreur, mais que c'est plutôt un comportement qui vous paraît trop lourd ou trop lent qui vous gêne, revoir le réglage d'effort (effort) de Claude Code permet d'ajuster l'équilibre entre la profondeur du raisonnement et la consommation de tokens. Lectures connexes : erreur 400 des blocs thinking, erreur de vérification d'état de PR, économie de tokens dans Claude Code, pourquoi il demande une permission en mode bypass, qu'est-ce que le MCP, et The model returned no content : causes et solutions.
FAQ
Q. Une erreur est apparue — que faire en premier ?
A. Lancez claude doctor. Il vérifie l'installation, les réglages, le MCP et le contexte d'un seul coup. Regardez ensuite /status (authentification actuelle) et /context (ce qui dévore le contexte), et vous pourrez généralement dire s'il s'agit d'un problème d'authentification, de contexte ou de connexion.
Q. J'atteins vite les limites de débit. Qu'est-ce qui aide ?
A. Chaque tour de Claude Code transporte le contenu de fichiers et des appels d'outils, et la documentation officielle indique qu'une seule session de débogage peut consommer plus qu'une journée de chat : vous les atteignez donc plus tôt que prévu. Vérifiez les limites et l'heure de réinitialisation avec /usage, passez à un modèle plus léger avec /model, réduisez l'historique avec /compact, et désactivez les MCP inutilisés. Si cela ne suffit pas, envisagez un forfait supérieur (Max, etc.) ou des crédits supplémentaires.
Q. Il affiche « Invalid API key » alors que ma clé devrait être correcte.
A. La cause classique est une variable d'environnement ANTHROPIC_API_KEY obsolète qui prend le pas sur votre abonnement. Vérifiez avec env | grep ANTHROPIC, unset ANTHROPIC_API_KEY (retirez-la aussi de votre profil de shell), puis /login et confirmez avec /status.
Q. Il ne se connecte pas sur mon réseau d'entreprise.
A. Confirmez d'abord la joignabilité avec curl -I https://api.anthropic.com. Pour un proxy, définissez HTTPS_PROXY ; pour l'inspection TLS, pointez NODE_EXTRA_CA_CERTS vers le certificat CA. N'utilisez pas NODE_TLS_REJECT_UNAUTHORIZED=0 — c'est dangereux. La bonne voie est de demander à la DSI d'autoriser api.anthropic.com.
Q. Rien de ce que j'essaie ne marche — dernier recours ?
A. Mettez à jour vers la dernière version avec claude update. Claude Code évolue vite et les bugs connus disparaissent souvent juste en montant de version. Si cela échoue encore, signalez-le avec /feedback (qui inclut le journal de conversation) à Anthropic.
