Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท HTTP, HTTPS, net, TLS, dgram and dns

Node.js autoSelectFamily (Happy Eyeballs) options

Reference for autoSelectFamily in Node.js: how net.connect() tries IPv6 and IPv4 addresses in turn, the attempt timeout, the default setters and the AggregateError result.

A host name can resolve to several addresses, often one IPv6 and one IPv4. If the first address does not answer, a client that gives up immediately feels broken, while a client that waits for the full TCP timeout feels slow. The "Happy Eyeballs" idea (RFC 8305) is to try the next address after a short delay. Node.js implements it with the autoSelectFamily option.

When autoSelectFamily is on, net.connect() asks the resolver for all addresses (dns.lookup() with all: true), tries the first one, and after autoSelectFamilyAttemptTimeout milliseconds starts the next in parallel without cancelling the first. The first connection that succeeds wins. It has been on by default since Node 20, and HTTP clients such as http.request() and fetch() use it too.

NODE
import net from 'node:net';

const socket = net.connect({
  port: 80,
  host: 'example.test',
  autoSelectFamily: true,
  autoSelectFamilyAttemptTimeout: 250,
});

Try it

Node.js Defaults and their setters

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js A first address that fails, a second that works

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
net.connect({ autoSelectFamily?: boolean, autoSelectFamilyAttemptTimeout?: number, ... })
net.getDefaultAutoSelectFamily(): boolean
net.setDefaultAutoSelectFamily(value: boolean): void
net.getDefaultAutoSelectFamilyAttemptTimeout(): number
net.setDefaultAutoSelectFamilyAttemptTimeout(value: number): void
socket.autoSelectFamilyAttemptedAddresses: string[]
Name Description
autoSelectFamily Whether to try all resolved addresses. Default comes from getDefaultAutoSelectFamily() (true).
autoSelectFamilyAttemptTimeout Milliseconds to wait before starting the next attempt. Default 250; the lowest allowed value is 10.
family When set to 4 or 6, only that family is resolved, so there is nothing to select between.
lookup Your own resolver. With autoSelectFamily it is called with options.all === true and must return an array of { address, family }.

Returns: the setters return nothing; the getters return the current defaults. The property autoSelectFamilyAttemptedAddresses lists the address:port strings tried, in order.

Errors and edge cases: if every address fails, the socket emits an AggregateError with code ECONNREFUSED (or the last failure's code) whose errors array holds one error per address. A single-address host behaves like a normal connect. Command-line flags --network-family-autoselection and --network-family-autoselection-attempt-timeout set the defaults for the whole process.

Usage notes

  • Why it exists. Many machines resolve localhost to ::1 first. A server that listens only on 127.0.0.1 used to give ECONNREFUSED; with the feature on, the client falls back to IPv4 automatically.
  • Order comes from the resolver. dns.lookup() follows the system order by default (verbatim); change it with dns.setDefaultResultOrder().
  • Custom lookup must handle all. A function that always returns a single address breaks the feature, as the second example's false run shows.
  • Slow networks. On high-latency links, a 250 ms attempt delay can start extra attempts; raise the timeout rather than disabling the feature.
  • Applies to net and users of it. tls.connect() and HTTP clients go through the same code path.
  • IP literals skip it. Connecting to 127.0.0.1 or ::1 directly involves no resolution and no selection.