localhost is not 127.0.0.1

Two Node default-policy changes drive every behavior in this article.

• v17 (2021): dns.lookup flipped verbatim from false to true. localhost now resolves to ::1 (IPv6) first on macOS. Permanent. v17 / v18 / v20 / v22 / v24 all do this.
• v20 (2023): net.connect flipped autoSelectFamily from false to true. Client connections to dual-family hostnames try IPv4 and IPv6 in parallel, falling back automatically (happy eyeballs, RFC 8305). Permanent. http.get, https.get, fetch all inherit this.

Three years apart. Most articles read them as one event. They are two separate policy shifts: First v17 changed the way localhost resolves, then v20 added a connect-side fallback so clients still worked despite the v17 default change.

I learned this the hard way. My backend listened on 127.0.0.1:1234. My frontend called localhost:1234. It just didn't connect, and the server logs were empty, so I had nothing to go on.

I figured 127.0.0.1 and localhost were interchangeable, which turns out to be wrong.

The bug

Node 17 changed dns.lookup defaults. Before v17 it post-sorted results to prefer IPv4. From v17 it returns whatever getaddrinfo gives back, no re-sorting. On macOS, getaddrinfo returns ::1 first for localhost when both A and AAAA records exist, no matter what order they sit in /etc/hosts.

# /etc/hosts (default macOS)
127.0.0.1    localhost
::1          localhost

Swap those two lines and behavior does not change. The OS resolver picks IPv6, not the file order.

My backend bound to 127.0.0.1, IPv4 only. My frontend resolved localhost to ::1, IPv6. The connection went to an address nobody was listening on. No error on the server because the request never arrived.

Frontend: fetch("http://localhost:1234")
           → DNS resolves localhost to ::1
           → connects to [::1]:1234
           → nothing listening there → connection refused

Backend:  listening on 127.0.0.1:1234
           → never sees the request
           → no error logged

The fix: bind to '::' (accepts both families on macOS and Linux) or to '0.0.0.0' (IPv4 only). Or use 127.0.0.1 in the frontend URL instead of localhost.

Three addresses, three meanings

They seem like the same thing at a glance, though they actually work in different ways.

# point localhost to a different loopback address
127.0.1.4    localhost

What I'd tell someone starting a local dev server

1. Listen on '::' when you want one socket that handles both families. macOS and Linux default to IPv6 sockets that accept IPv4 as well, making this the broadest "accept everything" option. Use '0.0.0.0' only if you specifically want IPv4 wildcard.
2. Connect to 127.0.0.1, not localhost. 127.0.0.1 is an IP literal, no DNS step, always IPv4. localhost goes through DNS, result depends on Node version and OS. This is the root cause of every FAIL in the tables below.
3. Silent failure = IPv4/IPv6 mismatch. No error, no log. The request went to an address nobody is listening on.

Full test results (Node 17 vs 22, macOS)

Six tables. Backend, optional proxy, and browser test every combination of localhost / 127.0.0.1 / 0.0.0.0 as listen and connect targets.

How dns.lookup('localhost') changed across Node versions

Node 17 changed how localhost resolves (IPv6 first). Node 20 added the fallback that lets clients still connect when ::1 fails. Two separate releases, two separate fixes, often conflated as "Node 17 fixed it" when v17 only did half the work.

Try it yourself

const http = require('http');
const dns = require('dns');
 
dns.lookup('localhost', (err, address, family) => {
  console.log(`dns.lookup → ${address} (IPv${family})`);
});
 
const server = http.createServer((req, res) => {
  res.writeHead(200);
  res.end('ok');
});
 
server.listen(9999, '127.0.0.1', () => {
  http.get('http://localhost:9999', () => {
    console.log('http.get → OK');
    server.close();
  }).on('error', (err) => {
    console.log('http.get → FAIL: ' + err.code);
    server.close();
  });
});

nvm use 18 && node test.js fails. nvm use 20 && node test.js succeeds. Same DNS result both times. The difference is happy eyeballs.

Reading the FAIL patterns

Every FAIL across the six tables maps to one of two mechanisms.

Category A. Server on IPv6 only, client uses IPv4 literal.

• Trigger: backend listen('localhost') (binds ::1) and client writes 127.0.0.1 or 0.0.0.0.
• Mechanism: client uses an IP literal, no DNS step, no second candidate to fall back to. Server has no IPv4 socket.
• Where: 2 cells in every table. No Node version fixes this.
• Fix: backend writes listen('0.0.0.0') or listen('::').

Category B. Client writes localhost from v17/v18, no happy eyeballs.

• Trigger: backend on IPv4 (127.0.0.1 or 0.0.0.0), client writes localhost from Node 17 or 18.
• Mechanism: client resolves localhost to ::1, server is not there, client gives up because v17/v18 has no fallback.
• Where: 2 extra cells in tables 3 and 5 (Node 17/18 proxy).
• Fix: upgrade client to Node 20+, or rewrite client to use 127.0.0.1.

What server.listen() actually binds to

Same across v17, v18, v20, v22, v24. listen('localhost') always binds IPv6 only.

Why doesn't the server fall back to IPv4 by itself?

Bind is atomic. The socket binds to one address, succeeds or fails. Once ::1 succeeds, Node has no reason to "try another." Happy eyeballs is a client-side TCP connect mechanism that tries multiple candidates in parallel. Server-side bind is passive, single-target, no analog.

If you want a server on both families, ask for it: listen('::') accepts IPv4 too on macOS and Linux. Or run two listens, one IPv4 and one IPv6.

Appendix: IPv6 link-local (fe80)

IPv6 introduced link-local addresses (fe80::/10). They work on a single network link without any router or DHCP. When a device joins a network, it assigns itself a fe80:: address automatically (SLAAC), uses it to discover the router via NDP, then gets a global IPv6 address.

Three rules for fe80 communication:

1. Same physical link (same Wi-Fi access point, same switch)
2. Same subnet
3. Same protocol (Wi-Fi and Ethernet can't cross-talk via fe80)

192.168.x.x is routed: packets go through the router. fe80:: is link-local: packets travel directly between devices on the same link, no router involved.

# Access a server on the same Wi-Fi via link-local (no router)
curl http://[fe80::xxxx:xxxx:xxxx:4c27%en0]:3000
 
# Access the same server via private IPv4 (through router)
curl http://192.168.1.42:3000

References

• Node.js DNS resolution change (issue #40537)
• http-proxy-middleware localhost resolution issue (#705)
• Accessing IPv6 link-local from browser (StackOverflow)
• Linux virtual network interfaces (thiscute.world)