Si vous continuez à utiliser Claude Code, vous finirez forcément par vous bloquer. Ce chapitre n'est pas un dictionnaire des erreurs. C'est un chapitre pour acquérir l'ordre de diagnostic qui descend du symptôme vers la cause.
Avec cet ordre en tête, même devant un message d'erreur que vous voyez pour la première fois, vous saurez juger de quelle famille il relève. Les articles de remède détaillés se lisent après, et cela suffit.
Ce qu'il faut faire avant de chercher le message d'erreur
Quand ils se bloquent, beaucoup de gens collent le message d'erreur dans un moteur de recherche. C'est utile aussi, mais dans la quasi-totalité des cas, vérifier trois choses d'abord va plus vite.
Si oui, la cause n'est pas l'environnement mais le changement juste avant. Une conversation qui s'est allongée, un réglage ajouté, un réseau changé.
À chaque fois, c'est la configuration ou l'environnement. De temps en temps, c'est la charge ou la ligne, et souvent la cause n'est pas de votre côté.
Au lancement, à l'instant où vous avez envoyé l'instruction, ou en pleine réponse ? L'endroit où cela s'est arrêté décide presque de la famille.
Le CHECK 3 est le plus efficace. Savoir où cela s'est arrêté dans la boucle collecter, agir, vérifier vue au chapitre 1 réduit les candidats d'un coup.
Ranger le problème dans l'une des cinq familles
Les erreurs de Claude Code se répartissent en cinq familles, selon l'endroit où se trouve la cause. Commencez par déterminer laquelle.
Est-ce qu'il démarre ?
Non → problème de l'application elle-même (voir le complément plus bas)
Oui
↓
Pouvez-vous envoyer une instruction ?
Non, il refuse → 1. Authentification
Oui
↓
Une réponse revient-elle ?
Non, rien n'arrive / cela se coupe → 2. Connexion
Il dit « limite » → 3. Plafonds d'utilisation
Il dit « trop long » → 4. Contexte
Oui
↓
Cela échoue dès qu'un outil externe intervient → 5. Outils et extensions
Faites votre pronostic avec cet arbre, puis allez à la section correspondante ci-dessous. Chaque famille a sa propre forme de remède, alors les mélanger fait fondre le temps.
1. Authentification : il n'accepte pas votre identité
Le symptôme : on vous dit que vous n'êtes pas connecté, ou bien vos identifiants sont refusés comme invalides. La signature de cette famille, c'est de s'arrêter avant l'envoi de l'instruction.
Session expirée / vous êtes entré avec un autre compte / confusion entre clé API et abonnement / le réseau de l'entreprise bloque le trafic d'authentification
Se reconnecter, puis vérifier avec quel compte vous êtes entré, puis essayer sur une autre ligne (partage de connexion, etc.). Si le troisième geste règle le problème, c'est la famille 2, la connexion
Comme cette famille se règle souvent par une reconnexion, on a tendance à s'y acharner quand cela ne suffit pas. Deux tentatives sans succès : passez aux soupçons de la famille 2. Le trafic d'authentification passe lui aussi par le réseau.
2. Connexion : rien n'arrive, ou cela se coupe
C'est la famille la plus souvent mal comprise. Ce n'est pas forcément votre configuration qui est en cause.
Le symptôme se décline en trois formes.
Proxy, TLS, blocage par le réseau d'entreprise. Un problème du côté de l'environnement, que l'on isole en changeant de ligne.
Le service est saturé. La bonne réponse est d'attendre ; toucher aux réglages ne laisse que des effets secondaires.
La connexion tombe au milieu d'une longue réponse. Découper la sortie en morceaux courts fait parfois disparaître le phénomène.
Chacune est traitée à part dans Corriger les erreurs de réseau, de proxy et de TLS, Les erreurs 529 Overloaded et 500 et Connection closed mid-response.
N'essayez pas de régler la saturation par la configuration. Si vous touchez à dix endroits pour reproduire un « ça échoue de temps en temps », vous ne saurez plus si c'est votre correction ou le temps qui a réglé l'affaire. Commencez par attendre un peu et réessayer, pour établir si cela se produit à chaque fois.
3. Plafonds d'utilisation : le quota est épuisé
La famille où l'on vous dit que vous avez atteint le plafond. Ce n'est pas une erreur mais le fonctionnement prévu, donc ce qu'il faut corriger n'est pas la configuration mais l'usage.
Ce qu'il faut retenir ici, c'est qu'il n'y a pas qu'un seul quota. Un quota à cycle court et un quota à cycle plus long existent séparément. Même si l'un se rétablit, tant que l'autre est épuisé, vous restez arrêté. C'est généralement l'explication du « c'était revenu tout à l'heure et c'est déjà bloqué à nouveau ».
Le détail est réuni dans Corriger usage limit reached et dans La vérité sur la réinitialisation anticipée du plafond hebdomadaire, qui vérifie le quota hebdomadaire par la mesure. Réduire la consommation elle-même, c'est le chapitre 7.
4. Contexte : l'entrée est trop longue
La famille où l'on vous refuse l'entrée parce qu'elle est trop longue. Voyez-la comme la fenêtre de contexte du chapitre 1 qui se manifeste directement sous forme de symptôme.
Repliez l'historique, ou coupez et repartez à neuf. Replier à une coupure du travail est la règle de base.
Ne collez pas un fichier ou un journal énorme en entier. Donnez seulement le passage concerné, ou faites-le chercher.
Le remède au symptôme est dans Prompt is too long : causes et solutions, et le jugement sur le moment de replier dans Faut-il lancer /compact à la main ?.
Notez qu'il arrive aussi qu'une sortie soit arrêtée pour non-respect des règles d'usage. Ce n'est pas un problème de longueur, ne confondez pas. C'est un cas d'un autre genre.
5. Outils et extensions : ce que vous avez branché ne marche pas
La famille qui apparaît après avoir ajouté un serveur MCP ou un outil externe. Le diagnostic est simple : regardez si le retirer règle le problème.
Désactiver toutes les extensions
→ réglé : la cause, ce sont les extensions. Les remettre une par une pour trouver le coupable
→ non réglé : les extensions n'y sont pour rien. Retour aux familles 1 à 4
Si ce sont bien les extensions, allez voir Les erreurs de connexion MCP : causes et solutions. C'est presque toujours l'un des trois : le format du réglage, le chemin de la commande de lancement, ou les permissions.
Ici, ne mettez pas en doute l'intelligence de Claude. Si une extension n'est pas connectée, Claude se comporte comme si l'outil n'existait pas. Un « je le lui ai dit et il ne le fait pas » dont la cause était la connexion, cela arrive souvent.
En complément : l'application elle-même ne démarre pas
Si vous utilisez l'application de bureau plutôt que la version terminal, il arrive que cela s'arrête avant même d'atteindre Claude Code. Comme ce n'est aucune des cinq familles, ce cas est sorti de l'arbre de diagnostic.
Le cas qui demande une réparation sous Windows est dans « Impossible d'ouvrir cette application » : la marche à suivre pour réparer, et celui qui fige à l'affichage dans Pourquoi GPU process gone fige tout, et comment y remédier.
Cinq gestes quand vous êtes toujours bloqué
Quand la famille vous échappe, ou qu'elle est identifiée mais que rien ne se règle. Essayez dans l'ordre, du haut vers le bas. Ils sont rangés du moins cher au plus cher.
Les troubles venant du contexte disparaissent ainsi. Le geste le moins cher.
La saturation et les plafonds se règlent avec cela seul. Ne touchez pas aux réglages.
Si cela règle le problème, la cause est bien le réseau de votre environnement.
Le diagnostic de la famille 5. On les remet une par une. Toutes d'un coup, cela n'a aucun sens.
Refaites la même chose dans un répertoire vide. Si cela ne se reproduit pas, la cause est dans le projet.
Ne changez qu'une chose à la fois. Quand on est bloqué, la panique donne envie de changer plusieurs choses en même temps, mais vous restez alors sans savoir ce qui a fait effet, et au prochain symptôme identique vous repartirez de zéro. Identifier le geste qui a marché est, sur la durée, incomparablement moins cher.
Si vous voulez chercher à partir d'un message d'erreur précis, Les erreurs fréquentes et comment les résoudre sert d'index.
Résumé
- Avant de chercher le message d'erreur, regardez trois choses : « est-ce que cela marchait il y a peu », « est-ce à chaque fois », « où cela s'est-il arrêté »
- Les causes se rangent en cinq familles : authentification, connexion, plafonds d'utilisation, contexte, outils. Ne les mélangez pas dans vos essais
- Face à la saturation et aux plafonds, la bonne réponse est d'attendre. Toucher aux réglages ne laisse que des effets secondaires
- Il n'y a pas qu'un seul quota. Un cycle court et un cycle long existent séparément, donc cela peut se rebloquer juste après être revenu
- La famille des extensions se tranche d'un seul geste : tout désactiver et voir si cela se règle. On les remet une par une
- Quand rien ne débloque, cinq gestes du moins cher au plus cher. Et ne changez qu'une chose à la fois
Une fois capable de sortir d'un blocage, il est temps de décider jusqu'où déléguer. Passez au chapitre 5, « Permissions et sécurité ».