ERR_CONNECTION_REFUSED / ECONNREFUSED (tested)

ERR_CONNECTION_REFUSED (Chrome) and ECONNREFUSED (Node, Python) mean the same thing: nothing was listening on that address and port, so the OS said no. Most of the time the server is down or on another port. The sneaky case is when it is running, but on 127.0.0.1 while the client tries ::1, or the other way round. We measured every combination.

1. What "connection refused" means

The client sent a TCP connect (SYN) and the other side answered with a reset right away. On the same machine that happens when no socket is listening on that exact IP address and port. The request never reached your app, so there is no HTTP status, no headers and no server log line.

It fails fast. Every refused connect in our tests failed in 0 ms. If you wait seconds and then fail, that is a timeout (firewall dropping packets), not a refusal. If the connection opens and then dies, see ERR_CONNECTION_RESET / ECONNRESET.

2. The exact error in each client

We pointed each client at a port with nothing listening.

Note the Node localhost case. If you only log err.cause.message, you log an empty string. Log err.cause.code and err.cause.errors too.

try {
  await fetch('http://localhost:3000/');
} catch (err) {
  const c = err.cause;
  console.log(c?.code, c?.message || c?.errors?.map(e => e.message));
}

3. localhost is two addresses

On our box /etc/hosts maps localhost to both 127.0.0.1 and ::1. The system resolver returns ::1 first. So did Python's socket.getaddrinfo. Node 24's dns.getDefaultResultOrder() is verbatim (the default since Node 17), so dns.lookup('localhost') also returned ::1 first.

That matters on both sides. A client asking for localhost tries ::1 first. A server told to listen on localhost picks one address only: our Node server given host: 'localhost' bound to [::1]:8990 and nothing else.

4. The matrix: bind address vs client target

We ran a Node http server bound to each address on port 8990, then connected with curl, Node fetch, Python urllib, Python requests, and Chromium (navigation and fetch). All five clients agreed in every cell.

Three things stand out:

• 0.0.0.0 is IPv4 only. It means "all IPv4 addresses". It does not accept [::1].
• :: is the only bind that accepted all three targets, because Linux lets an IPv6 socket also take IPv4 (our box has net.ipv6.bindv6only = 0). Turn on ipv6Only and 127.0.0.1 is refused again.
• localhost as a client target worked in every row. Modern clients try the next address when the first is refused. curl's verbose log shows it:

$ curl -v http://localhost:8990/      # server on 127.0.0.1 only
*   Trying [::1]:8990...
* connect to ::1 port 8990 from ::1 port 59782 failed: Connection refused
*   Trying 127.0.0.1:8990...
* Connected to localhost (127.0.0.1) port 8990

5. The Node 17+ localhost trap

Node 17 switched DNS results to verbatim order, so localhost became ::1 first. Servers that only listened on 127.0.0.1 then got ECONNREFUSED ::1:PORT. In Node 24 the fallback hides this for most code: net.getDefaultAutoSelectFamily() is true (250 ms per attempt), and fetch fell back to 127.0.0.1 in our test.

The trap still exists when the fallback is off. With a server on 127.0.0.1 only:

net.connect({ port: 8990, host: 'localhost', autoSelectFamily: false })
// error: ECONNREFUSED  connect ECONNREFUSED ::1:8990

net.connect({ port: 8990, host: 'localhost', autoSelectFamily: true })
// connected to 127.0.0.1

Libraries that pass their own lookup or family, older Node versions and other runtimes can still hit it. If your error says ::1 and your server listens on 127.0.0.1, this is it.

6. Defaults of common dev servers

• Flask 3.1.3 app.run() bound to 127.0.0.1:8990 only. curl http://[::1]:8990/ was refused; localhost worked through the fallback.
• Python 3.13 python3 -m http.server with no -b bound to 0.0.0.0 on our box (it printed "Serving HTTP on 0.0.0.0"). So [::1] is refused.
• Node listen(port, 'localhost') bound to ::1 only, as in the matrix.

7. Docker port publishing (from the Docker docs, not measured)

• -p 8080:80 publishes on all host interfaces. -p 127.0.0.1:8080:80 publishes on IPv4 loopback only, so [::1]:8080 on the host may be refused.
• The app inside the container must listen on 0.0.0.0 (or ::), not 127.0.0.1. Container loopback is not the host's loopback, so a server bound to 127.0.0.1 inside cannot be reached through the published port.
• Inside a container, localhost is the container itself. To reach another container use its service name; to reach the host, Docker Desktop provides host.docker.internal.

8. How to fix it

1. Is it running? ss -ltn | grep :PORT (Linux) or lsof -iTCP:PORT -sTCP:LISTEN (macOS). No line means nothing listens. Check the server's own log for a crash or "address in use".
2. Right port? Compare the port in the error with the one the server printed.
3. Right address? Compare the address in the error (::1 or 127.0.0.1) with the ss output. Use the matrix above.
4. Pick one fix: make the client use the exact address the server binds (http://127.0.0.1:3000), or bind the server to :: so both families work. Bind to 0.0.0.0/:: only if you mean to expose it on the network.
5. Proxy or container in between? If nginx shows 502 Bad Gateway, its error log (per the nginx docs and common reports, not measured) names the upstream with (111: Connection refused). Apply steps 1 to 3 to the upstream address.

Once it connects, check the real response with our HTTP headers tool.

Written with AI assistance. Measured on 2026-10-02 on Debian Linux with headless Chromium 153.0.8010.12 (Playwright), Node.js 24.21.0, curl 8.14.1, Python 3.13.5 (urllib, requests 2.32.3) and Flask 3.1.3. Test servers were Node http servers bound to six different addresses. Docker parts are from the Docker docs, not measured. PlainHeaders is our extension; curl, Python, Node.js and Chromium are free.