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 du 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, les 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 autoriser des outils spécifiques à 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 à nouveau le processus d’authentification

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 importantes
3. Considérez ajouter les grands 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

​

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

Si vous utilisez Claude Code dans les terminaux JetBrains et que 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. Cliquez sur le lien hypertexte “Configure terminal keybindings” à côté de “Override IDE Shortcuts”
3. Dans les raccourcis clavier du terminal, faites défiler vers le bas jusqu’à “Switch focus to Editor” et supprimez ce raccourci

Cela permettra à la touche ESC de fonctionner correctement pour annuler les opérations Claude Code au lieu d’être capturée par l’action “Switch focus to Editor” de PyCharm.

​

Problèmes de recherche et de 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 de 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 sur 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 passer par WSL, pour une meilleure performance du système de fichiers.

​

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, examinez-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