connect ECONNREFUSED 127.0.0.1:3000 — Why Nothing Is Listening and How to Fix It

ECONNREFUSED is the system error «Connection refused». The Linux connect(2) page says a connect() on a stream socket «found no one listening on the remote address», and the Node.js docs add: «This usually results from trying to connect to a service that is inactive on the foreign host.» In Node.js it looks like this:

Error: connect ECONNREFUSED 127.0.0.1:5432
    at TCPConnectWrap.afterConnect [as oncomplete] (node:net)  {
  errno: -111, code: 'ECONNREFUSED', syscall: 'connect', address: '127.0.0.1', port: 5432 }

The address and port in the message are the most useful part: they show where the client actually tried to connect, which is often not where you think. The host itself is up, since something answered with a refusal; that is what separates this error from ETIMEDOUT, where nothing answers at all. curl reports the same case as exit code 7, «Failed to connect() to host or proxy», and Chrome as ERR_CONNECTION_REFUSED.

A common surprise after a Node.js upgrade: connect ECONNREFUSED ::1:3000 while the server is clearly running. In Node.js 17.0.0 the default of dns.lookup()'s verbatim option became true, so addresses are returned in the order the resolver gives them instead of IPv4 first (Node.js dns docs). On many systems localhost resolves to ::1 first, and a server bound only to 127.0.0.1 refuses the IPv6 attempt.

Node.js 20.0.0 and 18.18.0 made autoSelectFamily default to true for net.connect(), which tries the other address family when the first fails (net docs), so the problem shows up less often, but tools and libraries with their own connect logic still hit it. Fixes, in order of preference:

• Connect to 127.0.0.1 explicitly instead of localhost.
• Make the server listen on both families (server.listen(3000, '::') on a dual-stack host).
• As a last resort, restore the old order with --dns-result-order=ipv4first or dns.setDefaultResultOrder('ipv4first').

Inside a container, localhost is the container itself, not your laptop and not the database container. An app container that connects to localhost:5432 gets ECONNREFUSED even though Postgres runs in the next container. On a user-defined network, containers reach each other by name: Docker's bridge network docs state that «User-defined bridges provide automatic DNS resolution between containers», while on the default bridge containers can only reach each other by IP address. In compose, every service gets a name on the project network:

services:
  app:
    environment:
      DATABASE_URL: postgres://app:secret@db:5432/app   # not localhost
  db:
    image: postgres:16

Also check the server inside the container: a dev server bound to 127.0.0.1 inside the container refuses connections from the published port. Bind it to 0.0.0.0.

1. Read the address and port in the error and test exactly that from the same machine or container:

   nc -vz 127.0.0.1 5432
   curl -v http://127.0.0.1:3000/

2. See what is listening on the target host:

   ss -ltnp | grep -E ':(3000|5432)\b'
   # LISTEN 0 511 127.0.0.1:3000 0.0.0.0:* users:(("node",pid=812,fd=21))

   A listener on 127.0.0.1 only accepts local connections; a missing line means the service is not running.
3. Check the service and its logs: systemctl status app, journalctl -u app -n 50, docker compose ps, docker compose logs db.
4. Check the firewall if the port listens but remote clients are refused: iptables -S | grep -i reject or nft list ruleset.
5. Wait for readiness in startup scripts. Retry the connection with backoff, or use a health check, instead of failing on the first refusal while a database is still starting.

Browser view of the same problem: ERR_CONNECTION_REFUSED.

nc -vz api.example.com 443
# Connection to api.example.com 443 port [tcp/https] succeeded!

Then rerun the client: the error should be gone, or turn into an application-level response. For a public host, the ping and port checker shows whether the port answers from outside your network.

• ETIMEDOUT — no answer at all, often a firewall that drops
• ECONNRESET — the connection opened and was then reset
• getaddrinfo ENOTFOUND — the host name did not resolve
• TypeError: Failed to fetch — a refused API call as the browser reports it
• Cloudflare error 521 — the origin refused Cloudflare's connection