Claude Code Erreurs de déploiement : Problèmes fréquents et guide de correction en 10 minutes

# L'un de ces trois messages indique un problème de clé API
Error: ANTHROPIC_API_KEY is not set
AuthenticationError: 401 {"type":"error","error":{"type":"authentication_error","message":"invalid x-api-key"}}
Error: Your API key is invalid.

# 1. Vérifier si la clé est définie dans le shell actuel
echo $ANTHROPIC_API_KEY

# 2. Définir temporairement (valable pour la session en cours uniquement)
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxx"

# 3. Écrire dans le fichier de config pour une persistance permanente (zsh: ~/.zshrc, bash: ~/.bashrc)
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc

# 4. Vérifier le format : doit commencer par sk-ant-api
claude --version

SyntaxError: Unexpected token '?'
engine "node" is incompatible with this module. Expected version ">=18". Got "16.x.x"
Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported.

# 1. Vérifier la version Node actuelle
node -v

# 2a. Changer de version avec nvm (recommandé)
nvm install 22
nvm use 22
nvm alias default 22

# 2b. Mettre à jour via Homebrew sur macOS
brew install node@22
brew link --overwrite node@22

# 3. Réinstaller Claude Code après la mise à jour
npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code

npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules'
Error: Permission denied (tool: bash)
EPERM: operation not permitted, unlink

# Changer le répertoire de packages global vers le dossier utilisateur — plus besoin de sudo
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

# Ajouter au PATH (mettre à jour la config shell, puis recharger)
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

# Réinstaller
npm install -g @anthropic-ai/claude-code

# Autoriser explicitement les outils au démarrage
claude --allowedTools "bash,read,write,edit"

# Ou configurer dans CLAUDE.md (persistance au niveau du projet)
# Pour les serveurs CI : --dangerously-skip-permissions ignore les confirmations interactives
# À utiliser uniquement dans des environnements de confiance
claude --dangerously-skip-permissions -p "your prompt here"

FetchError: request to https://api.anthropic.com/v1/messages failed, reason: connect ETIMEDOUT
Error: Network request failed: ENOTFOUND api.anthropic.com
ProxyError: tunneling socket could not be established, cause=connect ECONNREFUSED

# 1. Tester la connectivité directe
curl -v https://api.anthropic.com/v1/messages -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" -H "content-type: application/json" \
  -d '{"model":"claude-opus-4-5","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

# 2. Configurer un proxy HTTP
export HTTPS_PROXY="http://proxy.company.com:8080"
export HTTP_PROXY="http://proxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1"

# 3. Proxy avec authentification
export HTTPS_PROXY="http://username:password@proxy.company.com:8080"

# 4. URL de base personnalisée (passerelle interne d'entreprise)
export ANTHROPIC_BASE_URL="https://your-internal-gateway.company.com"

FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory
Killed (signal 9)   ← Arrêt forcé par le Linux OOM Killer
RangeError: Maximum call stack size exceeded

# 1. Augmenter la limite du tas Node.js (en Mo, selon la RAM disponible)
export NODE_OPTIONS="--max-old-space-size=4096"
claude

# 2. Vérifier l'utilisation mémoire actuelle
free -h          # Linux
vm_stat          # macOS

# 3. Pour les grandes bases de code, créer un .claudeignore
# node_modules/
# dist/
# .next/
# *.lock

# 4. Dans les longues conversations, utiliser /clear pour libérer la mémoire du contexte