Node.js Error ECONNREFUSED: Connection refused

Identify: does your log match?

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

1. High

   localhost resolves to IPv6 ::1

   Since Node 17, DNS results keep OS order, so localhost often becomes ::1. A server bound only to 127.0.0.1 refuses the IPv6 connection.

2. High

   Service not running or wrong port

   The database or API has not started yet, crashed, or listens on a different port than configured.

3. Medium

   localhost inside a container

   In Docker, localhost is the container itself; the database runs in another container reachable by service name.

Fix

const client = new pg.Client({ host: 'localhost', port: 5432 });

import dns from 'node:dns';
dns.setDefaultResultOrder('ipv4first'); // or run node --dns-result-order=ipv4first

const client = new pg.Client({ host: process.env.PGHOST ?? '127.0.0.1', port: 5432 });

Verify: reproduce it on purpose

$ node -e "require('net').connect(9, '127.0.0.1').on('error', e => console.log(e.code))"

Prevent

• Wait for dependencies with healthchecks, not sleep.
• Read host/port from env, never hardcode localhost.
• Retry startup connections with backoff.