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.
import net from 'node:net'; const socket = net.connect({ port: 80, host: 'example.test', autoSelectFamily: true, autoSelectFamilyAttemptTimeout: 250, });
Try it
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.
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
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
localhostto::1first. A server that listens only on127.0.0.1used to giveECONNREFUSED; 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 withdns.setDefaultResultOrder(). - Custom
lookupmust handleall. A function that always returns a single address breaks the feature, as the second example'sfalserun 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
netand users of it.tls.connect()and HTTP clients go through the same code path. - IP literals skip it. Connecting to
127.0.0.1or::1directly involves no resolution and no selection.