Node.js ECONNREFUSED: connection refused

What causes this error

When Node calls connect(2), the kernel sends a TCP SYN to the target. If no socket is listening on (host, port), the target replies with a RST packet. The kernel translates this into ECONNREFUSED (errno 61 macOS, 111 Linux). Common causes: target service crashed, wrong port, listening on 127.0.0.1 instead of 0.0.0.0, or a firewall rule actively rejecting (vs silently dropping).

How to fix it

1. 01

   step 1

   Verify the target service is running

   Don't assume. ps aux | grep <service> on the target machine, or for Docker, docker ps | grep <container>. A 'connection refused' on what should be a healthy service is your first signal that the service is actually dead.

   # On the target host
   ss -tlnp | grep :5432
   lsof -iTCP -sTCP:LISTEN | grep postgres

   Copy
2. 02

   step 2

   Check what address the target binds to

   A service bound to 127.0.0.1 only accepts connections from the same host. If your client is on a different host or in a different container, you need bind to 0.0.0.0 (all interfaces) or the specific reachable IP.

   ss -tlnp | grep :5432
   # LISTEN 0 128 127.0.0.1:5432  <- localhost only
   # LISTEN 0 128 0.0.0.0:5432    <- all interfaces

   Copy
3. 03

   step 3

   Test reachability from the client side

   Use nc -zv or curl from the client host to confirm. If nc says 'connection refused' too, the issue is between you and the target, not in your Node code.

   nc -zv 10.0.0.5 5432
   # nc: connect to 10.0.0.5 port 5432 (tcp) failed: Connection refused

   Copy
4. 04

   step 4

   Check container networking

   Docker Compose services reach each other by service name, not localhost. From service A, postgresql://db:5432 not localhost:5432. Each container has its own loopback. Same applies to Kubernetes pods: use the Service DNS name.

   # docker-compose.yml
   services:
     api:
       environment:
         DATABASE_URL: postgresql://user:pass@db:5432/app  # not localhost
     db:
       image: postgres:17

   Copy
5. 05

   step 5

   Add retry with exponential backoff for boot-time races

   On startup, your API container often starts before Postgres finishes initialising. ECONNREFUSED at t+0 is normal. Retry with backoff up to 30s, then fail.

   async function connectWithRetry(fn, maxAttempts = 10) {
     for (let i = 0; i < maxAttempts; i++) {
       try { return await fn() }
       catch (e) {
         if (e.code !== 'ECONNREFUSED') throw e
         await new Promise(r => setTimeout(r, Math.min(1000 * 2 ** i, 30000)))
       }
     }
     throw new Error('Connection refused after retries')
   }

   Copy
6. 06

   step 6

   Distinguish from ETIMEDOUT and EHOSTUNREACH

   ECONNREFUSED = host reachable, port closed (active reject). ETIMEDOUT = host not responding (firewall drop or down). EHOSTUNREACH = no route to host. The fix differs: refused = start the service; timeout = check firewalls; unreach = check routing.

   client.on('error', (err) => {
     switch (err.code) {
       case 'ECONNREFUSED': console.log('Service is down or wrong port')
       case 'ETIMEDOUT': console.log('Network or firewall issue')
       case 'EHOSTUNREACH': console.log('Routing problem')
     }
   })

   Copy