ERR_CONNECTION_REFUSED sur un domaine du fichier hosts : solutions

L'erreur ERR_CONNECTION_REFUSED sur un domaine défini dans le fichier hosts signifie que la résolution IP a réussi, mais qu'aucun serveur n'écoute sur le port cible à cette adresse. Votre ordinateur a bien converti le nom de domaine en adresse IP (par exemple 127.0.0.1), mais la tentative de connexion TCP a été immédiatement rejetée par le système.

Comment corriger ERR_CONNECTION_REFUSED sur un domaine du fichier hosts

Pour corriger ERR_CONNECTION_REFUSED sur un domaine du fichier hosts, vérifiez d'abord que votre serveur local est démarré sur le port demandé, précisez le numéro de port dans l'URL (ex: http://monapp.test:3000), liez votre serveur à 0.0.0.0 plutôt qu'à localhost, et assurez-vous que votre conteneur Docker publie bien ses ports vers la machine hôte.

Comprendre la mécanique de l'erreur

Le fichier hosts associe exclusivement un nom d'hôte à une adresse IP. Il ne traite jamais les numéros de ports ni les protocoles.

# Configuration valide dans /etc/hosts :
127.0.0.1  api.local.test

# Syntaxes invalides (ignorées ou provoquant des erreurs) :
127.0.0.1:3000 api.local.test
http://127.0.0.1 api.local.test

Lorsque vous saisissez http://api.local.test dans votre navigateur :

Consultez aussi notre guide complet sur la syntaxe du fichier hosts pour valider votre formatage.

Tableau de diagnostic rapide

1. Spécifier le numéro de port dans votre navigateur

Si votre serveur de développement tourne sur un port spécifique (3000 pour Next.js, 5173 pour Vite, 8080 pour Webpack) :

• Ne saisissez pas : http://api.local.test
• Saisissez : http://api.local.test:3000 ou http://api.local.test:5173

2. Identifier les processus en écoute

Vérifiez si votre application écoute bien sur le port attendu :

Sur macOS et Linux :

sudo lsof -nP -iTCP:80 -sTCP:LISTEN
sudo lsof -nP -iTCP:3000 -sTCP:LISTEN

Sur Windows (PowerShell en mode Administrateur) :

Get-NetTCPConnection -LocalPort 80,3000 -State Listen | Select-Object LocalAddress, LocalPort, OwningProcess

Si la commande sur votre port applicatif ne renvoie rien, votre serveur de développement n'est pas lancé.

3. Corriger le binding IP (127.0.0.1 vs 0.0.0.0 vs ::1)

De nombreux outils modernes lient par défaut le serveur de développement à localhost (qui résout souvent en IPv6 ::1). Si votre fichier hosts ne contient que la ligne IPv4 :

127.0.0.1 api.local.test

La connexion tentée en IPv4 est rejetée si le serveur n'écoute qu'en IPv6.

Pour résoudre ce conflit :

• Liez votre serveur à toutes les interfaces réseau (0.0.0.0) :
• Vite : vite --host 0.0.0.0
• Next.js : next dev -H 0.0.0.0
• Node/Express : app.listen(3000, '0.0.0.0')
• Ou déclarez les deux protocoles dans votre fichier hosts :

``text 127.0.0.1 api.local.test ::1 api.local.test ``

Pour aller plus loin sur cette distinction, lisez notre comparatif 0.0.0.0 vs 127.0.0.1 et 127.0.0.1 vs localhost.

4. Mettre en place un reverse proxy local (Caddy ou Nginx)

Pour accéder à vos domaines personnalisés sans devoir ajouter :3000 à chaque fois, utilisez un reverse proxy local comme Caddy.

Exemple de configuration dans un fichier Caddyfile :

api.local.test {
    reverse_proxy 127.0.0.1:3000
}

Lancez ensuite caddy run. Caddy écoute automatiquement sur les ports 80 et 443 et transfère le trafic vers votre serveur Node.js.

5. Vérifier les ports dans Docker

Si vous travaillez avec Docker, le conteneur doit explicitement publier son port vers l'hôte :

services:
  web:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"

Consultez aussi notre guide Docker et fichier hosts.

6. Vider le pool de sockets du navigateur

Google Chrome et Microsoft Edge maintiennent des connexions socket en mémoire qui peuvent conserver l'état d'échec :