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 | Aucune identification valide (token expiré, etc.) | /login. Si cela se répète, vérifiez l'horloge système et le verrouillage du trousseau |
| Invalid API key | Une ANTHROPIC_API_KEY obsolète subsiste | env | grep ANTHROPIC → unset ANTHROPIC_API_KEY → /login |
| OAuth token revoked / expired | Déconnecté ailleurs / désactivé par l'admin | /logout → /login. Soupçonnez aussi un décalage d'horloge |
| This organization has been disabled | Une clé API d'une organisation désactivée prend le dessus | Retirez la clé du profil du shell (.zshrc etc.) → /login → confirmez avec /status |
| 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.
3. Usage et limites de débit (le plus fréquent)
La plainte la plus fréquente avec Claude Code. Claude Code consomme 10 à 100 fois plus de tokens que le chat (conversations multi-tours, contextes énormes, allers-retours d'outils), si bien que 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 : « 429 / Request rejected » est un dépassement de débit sur votre clé API ou votre espace de travail. « Credit balance is too low » correspond à un solde prépayé de la Console épuisé (rechargez dans la facturation ou passez à un abonnement). À noter, vers mars 2026, des utilisateurs Max ont signalé que leurs fenêtres de 5 heures se vidaient anormalement vite dans la presse tech et dans les issues du dépôt officiel (bug suspecté). 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.
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 |
| Auto-compact 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.
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 |
| model not found / no access | Nom de modèle erroné ou non inclus dans votre forfait | /model pour resélectionner. Vérifiez une variable ANTHROPIC_MODEL obsolète |
| Opus is not available with Pro plan | Modèle sélectionné absent de votre forfait | /model vers un modèle disponible. Après un changement de forfait, /logout→/login |
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 |
| Multiple claude installations found | Doublons npm/Homebrew/native | Gardez-en une, 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) |
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 / ECONNREFUSED / ETIMEDOUT | 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 |
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 | Démarrage >5 s, etc. | MCP_TIMEOUT=10000 claude (ms). Par serveur : "timeout" dans .mcp.json |
9. Permissions et outils
La famille « on m'a demandé une permission même en mode bypass ». Le point clé : les règles deny l'emportent sur allow et bypass.
| Symptôme | Cause | Correctif |
|---|---|---|
| Asked for permission even in bypass mode | Les règles deny gagnent ; les opérations dangereuses demandent toujours une confirmation (coupe-circuit) | Vérifiez et ajustez les règles deny dans /permissions |
| 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. - 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é, les PDF de plus de 100 pages / 32 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 deny |
| 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.
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, et qu'est-ce que le MCP.
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. Claude Code consomme 10 à 100 fois plus de tokens que le 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.
