Dépannage de Claude Code

Problème. Claude Code a arrêté de fonctionner et tu ne sais pas pourquoi. La plupart des pannes viennent de cinq endroits, et une courte checklist permet de les trier. Parcours la liste dans l'ordre et tu seras de nouveau en train de taper des prompts en quelques minutes.

Checklist de diagnostic rapide :

# 1. Check your installation
claude --version
 
# 2. Test your internet connection
ping claude.ai
 
# 3. Verify your API key
echo $ANTHROPIC_API_KEY
 
# 4. Clear session state (inside Claude Code)
/clear
 
# 5. Restart with fresh config
claude config

Si une de ces commandes plante, saute directement à la section correspondante pour le correctif exact.

Problèmes d'installation

Erreur. command not found: claude

Le binaire n'a jamais atterri dans ton PATH, ou l'installation a complètement échoué. L'installateur natif règle ça tout seul :

# Reinstall with native installer (recommended)
curl -fsSL https://claude.ai/install.sh | bash  # macOS/Linux
# Windows PowerShell: irm https://claude.ai/install.ps1 | iex
 
# Verify installation
which claude

Erreur. Node.js version not supported

Node 18 ou supérieur est le minimum requis. Vérifie ce que tu as :

# Check current version
node --version
 
# If below 18.0, install latest Node.js
# Visit nodejs.org and download the LTS version

Erreur. EACCES permission denied

Sur macOS et Linux, les droits npm sont généralement en cause :

# Fix npm ownership
sudo chown -R $(whoami) ~/.npm
 
# Alternative: use a version manager like nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

Sur Windows, ouvre l'Invite de commandes en tant qu'Administrateur et relance l'installateur.

Problèmes d'authentification

Erreur. Invalid API key

Ta clé n'est pas définie ou elle est mauvaise. Reconfigure-la proprement :

# Reconfigure Claude Code
claude config
 
# Or set environment variable
export ANTHROPIC_API_KEY="your-api-key-here"

Récupère une nouvelle clé sur console.anthropic.com. Attention aux espaces parasites lors du copier-coller.

Erreur. Subscription not recognized

Pour les échecs d'auth Max et Pro :

1. Déconnecte-toi de Claude dans ton navigateur, complètement
2. Vide les cookies et les données en cache
3. Rouvre une fenêtre privée et reconnecte-toi
4. Relance claude config pour terminer la connexion

Problèmes de connexion

Erreur. 503 Service Unavailable

C'est du côté d'Anthropic, pas le tien :

• Attends 2 à 5 minutes, les serveurs récupèrent généralement
• status.anthropic.com confirme si quelque chose est en panne
• Réinstaller n'aide pas pour un problème serveur

Claude Code démarre mais reste silencieux

Efface l'état de session :

# Clear conversation history (run inside Claude Code)
/clear
 
# Or restart with fresh session
exit
claude

Toujours rien ? Confirme que ta connexion est active et réessaie.

Problèmes de performance

Réponses lentes ou blocage

Choisis un modèle plus rapide et réduis le contexte :

# Use Claude Sonnet 4 for speed
claude --model claude-sonnet-4-20250514
 
# Compress conversation history (run inside Claude Code)
/compact keep only function names and current errors

Erreur. Context window full

Le fil de discussion est devenu trop grand. Réinitialise-le ou compresse-le :

# Quick fix: start fresh (run inside Claude Code)
/clear
 
# Better fix: compress intelligently
/compact preserve main components and recent changes only

Erreurs de permissions de fichiers

Erreur. Permission denied on file operations

Les droits du répertoire ne sont pas corrects. Corrige ça :

# Check current permissions
ls -la
 
# Fix ownership of project directory
sudo chown -R $(whoami) .
 
# Verify Claude Code can access files
claude --add-dir $(pwd)

Problèmes de paramètres et de configuration

Paramètres qui se comportent bizarrement

Neuf fois sur dix, la priorité des portées est la raison. L'ordre est : Géré > Ligne de commande > Local > Projet > Utilisateur. Donc une clé dans .claude/settings.local.json bat la même clé dans .claude/settings.json, qui bat à son tour ~/.claude/settings.json.

# Check which settings files exist
ls ~/.claude/settings.json
ls .claude/settings.json
ls .claude/settings.local.json

Paramètres gérés qui écrasent tes préférences

Si l'IT a poussé un managed-settings.json, il est en haut de la pile et tu ne peux pas l'écraser. Les fichiers gérés se trouvent dans /Library/Application Support/ClaudeCode/ sur macOS, /etc/claude-code/ sur Linux et WSL, et C:\Program Files\ClaudeCode\ sur Windows. Si un paramètre revient sans cesse, demande à ton admin si une politique le fixe.

L'autocomplétion des paramètres ne fonctionne pas

Ajoute une ligne $schema en haut de ton settings.json pour que l'éditeur puisse valider et autocompléter :

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json"
}

Problèmes de sandbox et de sécurité

Erreur. bubblewrap not installed (Linux/WSL2)

Le sandboxing Linux dépend des paquets bubblewrap et socat. Installe les deux et relance :

# Debian/Ubuntu
sudo apt install bubblewrap socat
 
# Fedora
sudo dnf install bubblewrap socat

Watchman entre en conflit avec le sandbox

Le file watcher Watchman de Meta se bat avec le sandbox Claude Code. Désactive Watchman, ou garde-le en dehors de la limite du sandbox.

Les commandes Docker échouent dans le sandbox

Docker doit tourner en dehors du sandbox. Mets-le dans excludedCommands dans settings.json :

{
  "sandbox": {
    "enabled": true,
    "excludedCommands": ["docker", "docker-compose"]
  }
}

Variables d'environnement de débogage

Bloqué sur un bug tenace ? Ces variables d'env t'aident à isoler le problème :

# Run Claude Code with all non-essential traffic disabled
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 claude
 
# Or set just the auto-updater off
DISABLE_AUTOUPDATER=1 claude

Tu penses que c'est un problème de proxy ou de réseau ? Route le trafic avec HTTP_PROXY ou HTTPS_PROXY, et utilise NO_PROXY pour exclure des hôtes spécifiques du proxy.

Correctifs avancés

Toujours cassé ? Tout supprimer et recommencer :

# 1. Uninstall any existing installation
npm uninstall -g @anthropic-ai/claude-code  # if installed via npm
 
# 2. Remove config files
rm ~/.claude.json
rm -rf ~/.claude/
 
# 3. Fresh install with native installer (recommended)
curl -fsSL https://claude.ai/install.sh | bash  # macOS/Linux
# Windows PowerShell: irm https://claude.ai/install.ps1 | iex
 
# 4. Reconfigure
claude config

L'installateur natif configure PATH tout seul et se maintient à jour automatiquement.

Vérification du succès

Une fois le correctif appliqué, fais une vérification rapide :

# Test basic functionality
claude "write hello world in Python"
 
# Test file operations
echo "# Test" > test.md
claude "read and improve test.md"
 
# Test help command (inside Claude Code)
/help

Claude Code devrait répondre normalement maintenant. Si ce n'est toujours pas le cas, le problème est probablement côté serveur. Attends quelques minutes. Réessaie.