​
Problèmes d’installation courants

​
Problèmes de permissions Linux

Lors de l’installation de Claude Code avec npm, vous pourriez rencontrer des erreurs de permissions si votre préfixe global npm n’est pas accessible en écriture par l’utilisateur (par exemple /usr, ou /usr/local).

​
Solution recommandée : Créer un préfixe npm accessible en écriture par l’utilisateur

L’approche la plus sûre est de configurer npm pour utiliser un répertoire dans votre dossier personnel :

# D'abord, sauvegardez une liste de vos packages globaux existants pour une migration ultérieure
npm list -g --depth=0 > ~/npm-global-packages.txt

# Créez un répertoire pour vos packages globaux
mkdir -p ~/.npm-global

# Configurez npm pour utiliser le nouveau chemin de répertoire
npm config set prefix ~/.npm-global

# Note : Remplacez ~/.bashrc par ~/.zshrc, ~/.profile, ou autre fichier approprié pour votre shell
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc

# Appliquez le nouveau paramètre PATH
source ~/.bashrc

# Maintenant réinstallez Claude Code dans le nouvel emplacement
npm install -g @anthropic-ai/claude-code

# Optionnel : Réinstallez vos packages globaux précédents dans le nouvel emplacement
# Regardez ~/npm-global-packages.txt et installez les packages que vous voulez conserver

Cette solution est recommandée car elle :

  • Évite de modifier les permissions des répertoires système
  • Crée un emplacement propre et dédié pour vos packages npm globaux
  • Suit les meilleures pratiques de sécurité

​
Récupération système : Si vous avez exécuté des commandes qui changent la propriété et les permissions des fichiers système ou similaires

Si vous avez déjà exécuté une commande qui a changé les permissions des répertoires système (comme sudo chown -R $USER:$(id -gn) /usr && sudo chmod -R u+w /usr) et que votre système est maintenant cassé (par exemple, si vous voyez sudo: /usr/bin/sudo must be owned by uid 0 and have the setuid bit set), vous devrez effectuer des étapes de récupération.

Méthode de récupération Ubuntu/Debian :

  1. Pendant le redémarrage, maintenez SHIFT pour accéder au menu GRUB

  2. Sélectionnez “Options avancées pour Ubuntu/Debian”

  3. Choisissez l’option mode de récupération

  4. Sélectionnez “Drop to root shell prompt”

  5. Remontez le système de fichiers en écriture :

    mount -o remount,rw /

  6. Corrigez les permissions :

    # Restaurez la propriété root
chown -R root:root /usr
chmod -R 755 /usr

# Assurez-vous que /usr/local appartient à votre utilisateur pour les packages npm
chown -R YOUR_USERNAME:YOUR_USERNAME /usr/local

# Définissez le bit setuid pour les binaires critiques
chmod u+s /usr/bin/sudo
chmod 4755 /usr/bin/sudo
chmod u+s /usr/bin/su
chmod u+s /usr/bin/passwd
chmod u+s /usr/bin/newgrp
chmod u+s /usr/bin/gpasswd
chmod u+s /usr/bin/chsh
chmod u+s /usr/bin/chfn

# Corrigez la configuration sudo
chown root:root /usr/libexec/sudo/sudoers.so
chmod 4755 /usr/libexec/sudo/sudoers.so
chown root:root /etc/sudo.conf
chmod 644 /etc/sudo.conf

  7. Réinstallez les packages affectés (optionnel mais recommandé) :

    # Sauvegardez la liste des packages installés
dpkg --get-selections > /tmp/installed_packages.txt

# Réinstallez-les
awk '{print $1}' /tmp/installed_packages.txt | xargs -r apt-get install --reinstall -y

  8. Redémarrez :

    reboot
Méthode alternative de récupération par USB live :

Si le mode de récupération ne fonctionne pas, vous pouvez utiliser un USB live :

  1. Démarrez depuis un USB live (Ubuntu, Debian, ou toute distribution Linux)

  2. Trouvez votre partition système :

    lsblk

  3. Montez votre partition système :

    sudo mount /dev/sdXY /mnt  # remplacez sdXY par votre partition système réelle

  4. Si vous avez une partition de démarrage séparée, montez-la aussi :

    sudo mount /dev/sdXZ /mnt/boot  # si nécessaire

  5. Chroot dans votre système :

    # Pour Ubuntu/Debian :
sudo chroot /mnt

# Pour les systèmes basés sur Arch :
sudo arch-chroot /mnt

  6. Suivez les étapes 6-8 de la méthode de récupération Ubuntu/Debian ci-dessus

Après avoir restauré votre système, suivez la solution recommandée ci-dessus pour configurer un préfixe npm accessible en écriture par l’utilisateur.

​
Problèmes de mise à jour automatique

Si Claude Code ne peut pas se mettre à jour automatiquement, cela peut être dû à des problèmes de permissions avec votre répertoire de préfixe global npm. Suivez la solution recommandée ci-dessus pour corriger cela.

Si vous préférez désactiver la mise à jour automatique à la place, vous pouvez utiliser : Si vous préférez désactiver la mise à jour automatique à la place, vous pouvez définir la variable d’environnement DISABLE_AUTOUPDATER à 1

​
Permissions et authentification

​
Invites de permission répétées

Si vous vous trouvez à approuver de manière répétée 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 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 importantes
  3. Considérez l’ajout de 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 en cours
  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.

​
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