connect ECONNREFUSED ::1: why “localhost” fails when 127.0.0.1 works

localhost is a name with two addresses: 127.0.0.1 (IPv4) and ::1 (IPv6). If the client picks one and the server only listens on the other, the connection is refused even though the server is running.

What you see

Error: connect ECONNREFUSED ::1:5432          # Node.js 17+
Error: connect ECONNREFUSED ::1:3000          # fetch / axios to a local API
socket.error: [Errno 97] Address family not supported by protocol   # Python, IPv6 off
bind: Cannot assign requested address        # binding ::1 where IPv6 is disabled

The ::1 in the message is the giveaway: the client went to IPv6 loopback. Look up the server’s actual listening address:

ss -ltnp | grep 5432          # Linux
lsof -iTCP:5432 -sTCP:LISTEN  # macOS
# 127.0.0.1:5432  -> IPv4 only
# [::1]:5432      -> IPv6 only
# 0.0.0.0:5432 / *:5432 / [::]:5432 -> all addresses

Why it started happening

• Node.js 17+ stopped re-sorting DNS answers to put IPv4 first. Most systems list ::1 first for localhost, so Node now tries IPv6, while many dev databases and older servers listen on 127.0.0.1 only. Node 20+ fixes much of this with “happy eyeballs” (autoSelectFamily), which tries both.
• The reverse: a server bound to ::1 (or a localhost bind that resolved to IPv6) and a client that only tries 127.0.0.1.
• IPv6 disabled on the host or in a container: anything that resolves localhost to ::1 fails with “Address family not supported” or “Cannot assign requested address”.

Fixes, from quickest to best

1. Use the literal address in the client: postgres://[email protected]:5432/db, http://127.0.0.1:3000. Unambiguous and instant.
2. Prefer IPv4 in Node app-wide: node --dns-result-order=ipv4first app.js or dns.setDefaultResultOrder('ipv4first') at startup.
3. Make the server listen on both. Many servers accept a list or :: (dual-stack on Linux): PostgreSQL listen_addresses = 'localhost' covers both families; Node server.listen(3000) with no host listens on :: (and IPv4 too); Vite server.host, Python http.server --bind ::. Only listen beyond loopback if you really mean to: 0.0.0.0 and :: expose the port to the network unless a firewall stops it.
4. Check /etc/hosts (Windows: C:\Windows\System32\drivers\etc\hosts). It should contain both 127.0.0.1 localhost and ::1 localhost; a missing or edited line changes which one wins.

Docker and containers

Inside a container, localhost means the container itself, not your machine, so a database on the host is never at localhost from inside. Use the service name in Docker Compose (db:5432) or host.docker.internal. Port publishing like -p 127.0.0.1:5432:5432 binds IPv4 only on the host, so ::1 clients on the host are refused. Refused even with the right address and port? Work through localhost refused to connect and EADDRINUSE.

Reading the addresses

::1 is IPv6 shorthand for 127 zero bits followed by a 1; :: means “every address”. In URLs an IPv6 address needs square brackets: http://[::1]:3000/ (percent-encoding doesn’t replace them; see the URL encoder). 127.0.0.1 is the first address of the whole 127.0.0.0/8 loopback block; you can see it as one 32-bit number (2130706433) in the number base converter. Remote host timing out on port 22? See ssh Connection timed out port 22.

Related

TypeError: fetch failed (Node) · ssh Connection refused port 22 · ETIMEDOUT / connect ETIMEDOUT · getaddrinfo ENOTFOUND · ECONNRESET

Questions

Published 4 November 2026.