LightAtom

ECONNREFUSED: Connection Refused in Node.js

Node tried to connect and the target refused: no process listens on that address and port. On Macs, localhost resolving to IPv6 ::1 is a frequent cause.

Error: connect ECONNREFUSED 127.0.0.1:5432

Your Node app tried to connect to a service (a database, API or dev server) and the operating system replied that nothing is listening there.

Quick checks

  • Is the service running? Check with `lsof -nP -iTCP:PORT -sTCP:LISTEN`.
  • Read the address in the error: `::1` vs `127.0.0.1` matters.
  • In Docker, `localhost` means the container itself.

Fixes on Mac

  1. Start the service

    1. Postgres, Redis, MySQL: brew services list shows what's running; brew services start postgresql@16 starts it.

  2. Fix localhost vs ::1

    1. Since Node 17, localhost can resolve to IPv6 ::1 first. Node 20+ then tries IPv4 too, but Node 17–19 and many database drivers don't, so a service listening only on 127.0.0.1 refuses the ::1 attempt (connect ECONNREFUSED ::1:5432).
    2. Use 127.0.0.1 in the connection string, or make the service listen on both.

  3. Check the port

    1. Compare the port in your config with what the service actually uses (LightAtom's Ports view or lsof).

Fixes on Windows

  1. Windows

    1. netstat -ano | findstr :PORT shows whether anything listens; start the service.

Other devices

  1. Docker

    1. From a container to a service on the Mac, use host.docker.internal instead of localhost.
    2. Between containers, use the service name from Docker Compose.

Still not working?

If the service is running and listening and you still get ECONNREFUSED, a firewall rule may reject the connection, or the service listens on a different interface (for example only a Docker network).

See what’s happening

LightAtom's Ports view shows every listening port on your Mac, its process, and whether it listens on localhost only, a specific address or all interfaces.

Frequently asked questions

What does ECONNREFUSED mean in Node.js?

The connection was actively refused: the address and port have no listening process, or a firewall rejected it.

Why do I get ECONNREFUSED ::1?

localhost resolved to IPv6 ::1 but your service listens only on IPv4 127.0.0.1. Use 127.0.0.1 or configure the service to listen on ::1 too.

Why does localhost not work inside Docker?

Inside a container, localhost is the container. Use host.docker.internal to reach your Mac, or the other container's service name.

Related errors and tools

Related

LightAtom team

The people who build LightAtom, a network monitor for macOS.