NPM ETIMEDOUT - Erreur de connexion

Ce guide explique comment résoudre l'erreur ETIMEDOUT lors de l'installation de paquets npm.

Symptômes

npm error code ETIMEDOUT
npm error errno ETIMEDOUT
npm error network request to https://registry.npmjs.org/pm2 failed, reason:
npm error network This is a problem related to network connectivity.

Ou lors du téléchargement des tarballs :

npm http fetch GET 200 https://registry.npmjs.org/axios 21ms (cache hit)
npm http fetch GET https://registry.npmjs.org/axios/-/axios-1.13.2.tgz attempt 1 failed with ETIMEDOUT

Solution rapide (IPv6)

Dans la majorité des cas, le problème vient de la sélection automatique IPv4/IPv6 de Node.js.

export NODE_OPTIONS=--no-network-family-autoselection
npm install -g pm2

Pour rendre permanent, ajoutez dans ~/.bashrc ou ~/.profile :

echo 'export NODE_OPTIONS=--no-network-family-autoselection' >> ~/.bashrc
source ~/.bashrc

Autres solutions

1. Forcer IPv4 dans npm

npm config set prefer-ipv4 true
npm install -g pm2

2. Limiter les connexions simultanées

npm ouvre plusieurs connexions en parallèle, ce qui peut causer des timeouts :

npm config set maxsockets 1
npm install -g pm2

Après résolution, vous pouvez remonter à 5-10 pour de meilleures performances.

3. Vérifier le registre npm

Assurez-vous d'utiliser HTTPS :

npm config get registry

Si le résultat est http://..., corrigez :

npm config set registry https://registry.npmjs.org/

4. Vider le cache npm

npm cache clean --force
npm install -g pm2

5. Vérifier la connectivité réseau

# Test DNS
ping -c 3 registry.npmjs.org

# Test HTTPS
curl -I https://registry.npmjs.org/pm2

6. Vérifier la configuration DNS

cat /etc/resolv.conf

Si vide ou mal configuré :

echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
echo "nameserver 1.1.1.1" | sudo tee -a /etc/resolv.conf

7. Vérifier le firewall

Le trafic sortant HTTPS (port 443) doit être autorisé :

# UFW
sudo ufw status

# iptables
sudo iptables -L OUTPUT -n -v

8. Supprimer un proxy mal configuré

npm config list

Si un proxy est configuré par erreur :

npm config delete proxy
npm config delete https-proxy

Diagnostic avec verbose

Pour comprendre où ça bloque :

npm install -g pm2 --verbose

Vous verrez les requêtes HTTP et où le timeout se produit.

Récapitulatif des commandes

# Solution 1 : Désactiver la sélection auto IPv4/IPv6 (recommandé)
export NODE_OPTIONS=--no-network-family-autoselection

# Solution 2 : Forcer IPv4
npm config set prefer-ipv4 true

# Solution 3 : Limiter les connexions
npm config set maxsockets 1

# Solution 4 : Tout réinitialiser
npm cache clean --force
npm config set registry https://registry.npmjs.org/

# Tester
npm install -g pm2

Configuration permanente

Pour éviter ce problème à l'avenir, ajoutez à ~/.bashrc :

# Fix npm ETIMEDOUT
export NODE_OPTIONS=--no-network-family-autoselection

Ou configurez npm globalement :

npm config set prefer-ipv4 true
npm config set maxsockets 5

Conseil

Si les métadonnées (JSON) passent mais pas les téléchargements (.tgz), c'est généralement un problème IPv6 ou de connexions simultanées.