Claude Code ne fonctionne pas : diagnostic

Quand Claude Code ne démarre pas, le message utile est celui du terminal, pas un forum. La page « Troubleshoot installation and login » sépare l'installation et la connexion des pannes qui arrivent une fois le programme lancé. Celles-là sont sur « Troubleshooting ». Les commandes ci-dessous viennent de ces deux pages, relues le 19 octobre 2026. Elles n'ont pas été rejouées ici. Aucune sortie n'est donc recopiée.

Si l'installation elle-même n'a pas encore été faite, le guide Installer Claude Code suit une autre page. Ce texte-ci suppose que vous avez déjà tenté un lancement, ou que claude ne répond pas.

Prérequis

Un terminal, et une idée de ce qui casse. Deux cas ne se traitent pas pareil.

Si claude ne démarre pas du tout, la page Troubleshooting dit de lancer claude doctor depuis le shell. Si une session s'ouvre, la même page dit de lancer /doctor dedans. /doctor propose des corrections après confirmation. claude doctor, lancé hors session, imprime un diagnostic d'installation et de réglages, sans ouvrir de conversation. La page « Debug your configuration », citée par Troubleshooting, décrit le même partage. Ce guide ne recopie pas les commandes de cette troisième page.

L'extension VS Code ne place pas claude dans ~/.local/bin. La page d'installation dit que l'extension garde une copie privée pour son panneau. Si seul l'éditeur est installé, l'absence du binaire dans ce dossier n'est pas une installation cassée. Il faut l'installateur autonome pour avoir la commande dans un terminal. Le détail est dans le guide d'installation.

La commande est introuvable

La page d'installation associe command not found: claude et 'claude' is not recognized à un PATH incomplet. L'installateur natif pose le programme dans ~/.local/bin/claude sur macOS et Linux, et dans %USERPROFILE%\.local\bin\claude.exe sur Windows. Il peut signaler le cas sous Setup notes: sans modifier le PATH lui-même.

Vérifiez d'abord que le fichier existe. Commande macOS et Linux tirée de la page d'installation, relue le 19 octobre 2026 et non rejouée :

ls -la ~/.local/bin/claude

No such file or directory veut dire qu'il n'y a pas d'installation native à cet endroit. Une installation npm, Homebrew ou par paquet peut exister ailleurs. Ne corrigez pas le PATH avant d'avoir trouvé le binaire.

Si le fichier est listé, la même page filtre le PATH :

echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"

Aucune ligne, et le dossier n'est pas dans le PATH. Pour Zsh, shell par défaut sur macOS, la page donne :

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Pour Bash sur Linux :

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Sur macOS, Bash est un shell de login et ignore ~/.bashrc. La page dit d'écrire dans ~/.bash_profile, ou dans ~/.bash_login ou ~/.profile si l'un de ces fichiers existe déjà et que ~/.bash_profile n'existe pas. Un permission denied sur le echo n'est pas un PATH à deviner : la page a une section à part pour un fichier de configuration non inscriptible.

Puis :

claude --version

La page dit que la commande imprime un numéro de version, avec un exemple du type 2.1.211 (Claude Code). Cet exemple est celui de la documentation. Il n'a pas été produit ici, et il ne dit pas quelle version vous avez.

Un terminal déjà ouvert garde l'ancien PATH. Une fenêtre intégrée à un éditeur hérite du PATH de l'éditeur. Ouvrez une nouvelle fenêtre avant de conclure que la correction a échoué.

Sur Windows, la même page documente d'autres commandes, dans PowerShell et dans CMD. Ne collez pas les lignes macOS dans PowerShell : curl y est un alias, et -fsSL n'est pas un paramètre de cet alias. Le message 'bash' is not recognized as the name of a cmdlet veut dire que la commande d'installation macOS ou Linux a été collée sur Windows.

Le téléchargement ne répond pas

L'installateur récupère les binaires sur downloads.claude.ai. La page d'installation propose, sur macOS et Linux :

curl -sI https://downloads.claude.ai/claude-code-releases/latest

Elle dit qu'un accès réussi commence par un statut 200 : HTTP/2 200 sur macOS et Linux, HTTP/1.1 200 OK avec le curl.exe de Windows. Ce guide n'a pas lancé la requête. Un 403 est, selon la page, souvent un proxy, un filtre, ou une indisponibilité régionale. La page renvoie à la liste des pays pris en charge sur anthropic.com. Un 5xx est traité comme un incident temporaire. Pas de sortie, Could not resolve host, ou un délai dépassé : le réseau bloque. La page cite alors un pare-feu, un proxy, ou des certificats à mettre à jour.

Si un proxy d'entreprise est obligatoire, la page montre comment définir HTTP_PROXY et HTTPS_PROXY avant l'installateur. Le nom d'hôte de l'exemple n'est pas le vôtre. Demandez l'adresse au réseau interne plutôt que de recopier proxy.example.com.

App unavailable in region est une ligne du tableau de la même page. Ce n'est pas un PATH.

La session part, puis se fige

Là, la page Troubleshooting s'applique. Si Claude Code ne répond plus :

Ctrl+C pour tenter d'annuler l'opération en cours.
Si rien ne bouge, fermer le terminal.

La page dit qu'un redémarrage ne perd pas la conversation, et que claude --resume, dans le même répertoire, la reprend. Cette reprise n'a pas été essayée ici.

Pour savoir si un plugin, un serveur MCP ou un hook mange les ressources, la page donne un redémarrage sans personnalisation :

claude --safe-mode

Le drapeau désactive les personnalisations pour cette session. Si l'usage baisse, la page renvoie à « Debug your configuration » pour trouver lequel. Elle ne dit pas que le mode sûr corrige le fichier en cause.

/compact réduit le contexte. S'il répond Not enough messages to compact., la conversation a trop peu de tours à résumer, même si une seule grande copie a rempli la fenêtre. /mcp affiche l'état des serveurs MCP. Ces deux commandes se tapent dans une session, pas dans le shell.

Une recherche qui ne trouve rien peut venir du ripgrep livré avec Claude Code. La page Troubleshooting dit alors d'installer le paquet ripgrep du système et de mettre USE_BUILTIN_RIPGREP à 0, dans l'environnement ou dans le bloc env de settings.json. Pour confirmer, elle dit de relancer claude doctor et de regarder si la ligne Search montre le chemin du binaire système plutôt que OK (bundled). Sans exécution, ce guide ne peut pas dire ce que votre ligne Search contient.

Sur WSL, la même page avertit que lire un projet posé sur /mnt/c/ peut renvoyer moins de correspondances qu'un projet sous /home/. Ce n'est pas une recherche cassée au sens d'un binaire absent.

Quand doctor ne rend rien

La page d'installation associe deux symptômes au même contrôle : claude update reste sur Checking for updates, ou claude doctor ne produit aucune sortie. Elle demande alors de déplacer le répertoire qui occupe par erreur l'emplacement d'un fichier de configuration du shell. Elle ne donne plus, dans la version consultée, de numéro de version à partir duquel ce défaut serait corrigé.

Ne supprimez pas ce répertoire sans savoir ce qu'il contient. Ouvrez la section correspondant exactement à ce message dans la documentation d'installation et suivez les chemins indiqués pour votre shell. Aucune commande de déplacement n'a été exécutée ici.

Vérification

Deux commandes, dans cet ordre, une fois le PATH corrigé et un nouveau terminal ouvert :

claude --version

claude doctor

La première doit imprimer une version, selon la page d'installation. La seconde doit rendre un rapport, sauf le cas du répertoire de configuration décrit plus haut. Si claude --version fonctionne et que le reste non, la page dit de lancer claude doctor pour un rapport automatique. Si une session s'ouvre, /doctor et /mcp sont les deux contrôles nommés en fin de page Troubleshooting. /feedback envoie un rapport à Anthropic depuis la session. Pour un compte, une facturation ou un abonnement, la page renvoie vers l'aide de claude.ai ou de platform.claude.com, pas vers une commande shell.

Aucune de ces commandes n'a été exécutée pour rédiger ce guide. Si la sortie ne ressemble pas à ce que la page décrit, suivez la page, pas ce texte.

Sources

Documentation officielle Anthropic consultée le 19 octobre 2026 :

La troisième page confirme la différence entre claude doctor et /doctor ; aucune procédure supplémentaire n’en a été tirée. Les numéros de version cités sont ceux de la documentation, pas une mesure de cette machine. Pas de capture, pas de tarif, pas de lien d'affiliation.