Dépannage

​

Problèmes d’installation courants

​

Problèmes d’installation Windows : erreurs dans WSL

Vous pourriez rencontrer les problèmes suivants dans WSL :

Problèmes de détection OS/plateforme : Si vous recevez une erreur lors de l’installation, WSL pourrait utiliser le npm de Windows. Essayez :

• Exécutez npm config set os linux avant l’installation
• Installez avec npm install -g @anthropic-ai/claude-code --force --no-os-check (N’utilisez PAS sudo)

Erreurs Node non trouvé : Si vous voyez exec: node: not found lors de l’exécution de claude, votre environnement WSL pourrait utiliser une installation Windows de Node.js. Vous pouvez le confirmer avec which npm et which node, qui devraient pointer vers des chemins Linux commençant par /usr/ plutôt que /mnt/c/. Pour corriger cela, essayez d’installer Node via le gestionnaire de paquets de votre distribution Linux ou via nvm.

Conflits de version nvm : Si vous avez nvm installé à la fois dans WSL et Windows, vous pourriez rencontrer des conflits de version lors du changement de versions Node dans WSL. Cela se produit parce que WSL importe le PATH Windows par défaut, causant la priorité de nvm/npm Windows sur l’installation WSL.

Vous pouvez identifier ce problème en :

• Exécutant which npm et which node - s’ils pointent vers des chemins Windows (commençant par /mnt/c/), les versions Windows sont utilisées
• Rencontrant des fonctionnalités cassées après avoir changé les versions Node avec nvm dans WSL

Pour résoudre ce problème, corrigez votre PATH Linux pour assurer que les versions Linux node/npm prennent la priorité :

Solution principale : Assurez-vous que nvm est correctement chargé dans votre shell

La cause la plus commune est que nvm n’est pas chargé dans les shells non-interactifs. Ajoutez ce qui suit à votre fichier de configuration shell (~/.bashrc, ~/.zshrc, etc.) :

# Load nvm if it exists
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

Ou exécutez directement dans votre session actuelle :

source ~/.nvm/nvm.sh

Alternative : Ajuster l’ordre PATH

Si nvm est correctement chargé mais les chemins Windows prennent encore la priorité, vous pouvez explicitement préfixer vos chemins Linux au PATH dans votre configuration shell :

export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"

​

Problèmes d’installation Linux et Mac : erreurs de permission ou commande non trouvée

Lors de l’installation de Claude Code avec npm, des problèmes de PATH peuvent empêcher l’accès à claude. Vous pourriez aussi rencontrer des erreurs de permission si votre préfixe global npm n’est pas accessible en écriture par l’utilisateur (ex. /usr, ou /usr/local).

​

Solution recommandée : Installation native de Claude Code

Claude Code a une installation native qui ne dépend pas de npm ou Node.js.

Utilisez la commande suivante pour exécuter l’installateur natif.

macOS, Linux, WSL :

# Install stable version (default)
curl -fsSL https://claude.ai/install.sh | bash

# Install latest version
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Install specific version number
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

Windows PowerShell :

# Install stable version (default)
irm https://claude.ai/install.ps1 | iex

# Install latest version
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest

# Install specific version number
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

Cette commande installe la version appropriée de Claude Code pour votre système d’exploitation et architecture et ajoute un lien symbolique vers l’installation à ~/.local/bin/claude.

​

Solution alternative : Migrer vers une installation locale

Alternativement, si Claude Code fonctionne, vous pouvez migrer vers une installation locale :

claude migrate-installer

Cela déplace Claude Code vers ~/.claude/local/ et configure un alias dans votre configuration shell. Aucun sudo n’est requis pour les futures mises à jour.

Après la migration, redémarrez votre shell, puis vérifiez votre installation :

Sur macOS/Linux/WSL :

which claude  # Should show an alias to ~/.claude/local/claude

Sur Windows :

where claude  # Should show path to claude executable

Vérifiez l’installation :

claude doctor # Check installation health

​

Permissions et authentification

​

Invites de permission répétées

Si vous vous trouvez à approuver répétitivement les mêmes commandes, vous pouvez permettre à des outils spécifiques de s’exécuter sans approbation en utilisant la commande /permissions. Voir Documentation des permissions.

​

Problèmes d’authentification

Si vous rencontrez des problèmes d’authentification :

1. Exécutez /logout pour vous déconnecter complètement
2. Fermez Claude Code
3. Redémarrez avec claude et complétez le processus d’authentification à nouveau

Si les problèmes persistent, essayez :

rm -rf ~/.config/claude-code/auth.json
claude

Cela supprime vos informations d’authentification stockées et force une connexion propre.

​

Performance et stabilité

​

Utilisation élevée du CPU ou de la mémoire

Claude Code est conçu pour fonctionner avec la plupart des environnements de développement, mais peut consommer des ressources significatives lors du traitement de grandes bases de code. Si vous rencontrez des problèmes de performance :

1. Utilisez /compact régulièrement pour réduire la taille du contexte
2. Fermez et redémarrez Claude Code entre les tâches majeures
3. Considérez ajouter de gros répertoires de build à votre fichier .gitignore

​

La commande se bloque ou se fige

Si Claude Code semble ne pas répondre :

1. Appuyez sur Ctrl+C pour tenter d’annuler l’opération actuelle
2. Si non réactif, vous pourriez avoir besoin de fermer le terminal et redémarrer

​

Problèmes de recherche et découverte

Si l’outil de recherche, les mentions @file, les agents personnalisés, et les commandes slash personnalisées ne fonctionnent pas, installez ripgrep système :

# macOS (Homebrew)  
brew install ripgrep

# Windows (winget)
winget install BurntSushi.ripgrep.MSVC

# Ubuntu/Debian
sudo apt install ripgrep

# Alpine Linux
apk add ripgrep

# Arch Linux
pacman -S ripgrep

Puis définissez USE_BUILTIN_RIPGREP=0 dans votre environnement.

​

Résultats de recherche lents ou incomplets sur WSL

Les pénalités de performance de lecture disque lors du travail à travers les systèmes de fichiers sur WSL peuvent résulter en moins de correspondances que prévu (mais pas un manque complet de fonctionnalité de recherche) lors de l’utilisation de Claude Code sur WSL.

Solutions :

1. Soumettez des recherches plus spécifiques : Réduisez le nombre de fichiers recherchés en spécifiant des répertoires ou types de fichiers : “Rechercher la logique de validation JWT dans le package auth-service” ou “Trouver l’utilisation du hash md5 dans les fichiers JS”.

2. Déplacez le projet vers le système de fichiers Linux : Si possible, assurez-vous que votre projet est situé sur le système de fichiers Linux (/home/) plutôt que le système de fichiers Windows (/mnt/c/).

3. Utilisez Windows natif à la place : Considérez exécuter Claude Code nativement sur Windows au lieu de via WSL, pour une meilleure performance du système de fichiers.

​

Problèmes d’intégration IDE

​

IDE JetBrains non détecté sur WSL2

Si vous utilisez Claude Code sur WSL2 avec les IDEs JetBrains et obtenez des erreurs “No available IDEs detected”, c’est probablement dû à la configuration réseau de WSL2 ou au Pare-feu Windows bloquant la connexion.

​

Modes réseau WSL2

WSL2 utilise le réseau NAT par défaut, ce qui peut empêcher la détection IDE. Vous avez deux options :

Option 1 : Configurer le Pare-feu Windows (recommandé)

1. Trouvez votre adresse IP WSL2 :

   wsl hostname -I
   # Example output: 172.21.123.456
   

2. Ouvrez PowerShell en tant qu’Administrateur et créez une règle de pare-feu :

   New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16
   

   (Ajustez la plage IP basée sur votre sous-réseau WSL2 de l’étape 1)

3. Redémarrez à la fois votre IDE et Claude Code

Option 2 : Passer au réseau miroir

Ajoutez à .wslconfig dans votre répertoire utilisateur Windows :

[wsl2]
networkingMode=mirrored

Puis redémarrez WSL avec wsl --shutdown depuis PowerShell.

Pour des conseils de configuration JetBrains supplémentaires, voir notre guide d’intégration IDE.

​

Signaler les problèmes d’intégration IDE Windows (natif et WSL)

Si vous rencontrez des problèmes d’intégration IDE sur Windows, veuillez créer un problème avec les informations suivantes : si vous êtes natif (git bash), ou WSL1/WSL2, mode réseau WSL (NAT ou miroir), nom/version IDE, version extension/plugin Claude Code, et type de shell (bash/zsh/etc)

​

La touche ESC ne fonctionne pas dans les terminaux JetBrains (IntelliJ, PyCharm, etc.)

Si vous utilisez Claude Code dans les terminaux JetBrains et la touche ESC n’interrompt pas l’agent comme attendu, c’est probablement dû à un conflit de raccourci clavier avec les raccourcis par défaut de JetBrains.

Pour corriger ce problème :

1. Allez dans Paramètres → Outils → Terminal
2. Soit :
   • Décochez “Move focus to the editor with Escape”, ou
   • Cliquez “Configure terminal keybindings” et supprimez le raccourci “Switch focus to Editor”
3. Appliquez les changements

Cela permet à la touche ESC d’interrompre correctement les opérations Claude Code.

​

Problèmes de formatage Markdown

Claude Code génère parfois des fichiers markdown avec des balises de langage manquantes sur les clôtures de code, ce qui peut affecter la coloration syntaxique et la lisibilité dans GitHub, les éditeurs, et les outils de documentation.

​

Balises de langage manquantes dans les blocs de code

Si vous remarquez des blocs de code comme ceci dans le markdown généré :

```
function example() {
  return "hello";
}
```

Au lieu de blocs correctement balisés comme :

```javascript
function example() {
  return "hello";
}
```

Solutions :

1. Demandez à Claude d’ajouter des balises de langage : Demandez simplement “Veuillez ajouter des balises de langage appropriées à tous les blocs de code dans ce fichier markdown.”

2. Utilisez des hooks de post-traitement : Configurez des hooks de formatage automatique pour détecter et ajouter les balises de langage manquantes. Voir l’exemple de hook de formatage markdown pour les détails d’implémentation.

3. Vérification manuelle : Après avoir généré des fichiers markdown, révisez-les pour un formatage approprié des blocs de code et demandez des corrections si nécessaire.

​

Espacement et formatage incohérents

Si le markdown généré a des lignes vides excessives ou un espacement incohérent :

Solutions :

1. Demandez des corrections de formatage : Demandez à Claude de “Corriger les problèmes d’espacement et de formatage dans ce fichier markdown.”

2. Utilisez des outils de formatage : Configurez des hooks pour exécuter des formateurs markdown comme prettier ou des scripts de formatage personnalisés sur les fichiers markdown générés.

3. Spécifiez les préférences de formatage : Incluez les exigences de formatage dans vos invites ou fichiers de mémoire de projet.

​

Meilleures pratiques pour la génération markdown

Pour minimiser les problèmes de formatage :

• Soyez explicite dans les demandes : Demandez du “markdown correctement formaté avec des blocs de code balisés par langage”
• Utilisez les conventions de projet : Documentez votre style markdown préféré dans CLAUDE.md
• Configurez des hooks de validation : Utilisez des hooks de post-traitement pour vérifier et corriger automatiquement les problèmes de formatage courants

​

Obtenir plus d’aide

Si vous rencontrez des problèmes non couverts ici :

1. Utilisez la commande /bug dans Claude Code pour signaler les problèmes directement à Anthropic
2. Vérifiez le dépôt GitHub pour les problèmes connus
3. Exécutez /doctor pour vérifier la santé de votre installation Claude Code
4. Demandez directement à Claude sur ses capacités et fonctionnalités - Claude a un accès intégré à sa documentation