Node.js Reference ยท HTTP, HTTPS, net, TLS, dgram and dns
Node.js dns.setDefaultResultOrder() method
Reference for dns.setDefaultResultOrder() and getDefaultResultOrder() in Node.js: control whether IPv4 or IPv6 addresses come first in lookups.
When a host name has both IPv4 and IPv6 addresses, the order in which dns.lookup() returns them decides which one a client tries first. dns.setDefaultResultOrder() sets that order for the whole process; dns.getDefaultResultOrder() reads it.
Since Node 17 the default is 'verbatim': addresses are returned exactly as the resolver gave them, usually with IPv6 first. Before that, Node moved IPv4 addresses to the front. Programs that suddenly could not reach localhost after an upgrade (the server listens on 127.0.0.1 but localhost now resolves to ::1 first) are the classic symptom.
import dns from 'node:dns'; dns.setDefaultResultOrder('ipv4first'); console.log(dns.getDefaultResultOrder()); // 'ipv4first'
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
dns.setDefaultResultOrder(order) dns.getDefaultResultOrder(): 'verbatim' | 'ipv4first' | 'ipv6first' // also on node:dns/promises
| Name | Description |
|---|---|
order |
'verbatim': keep the resolver's order. 'ipv4first': IPv4 addresses first. 'ipv6first': IPv6 addresses first. |
Returns: setDefaultResultOrder() returns undefined; getDefaultResultOrder() returns the current setting as a string.
Errors: any other value throws ERR_INVALID_ARG_VALUE synchronously, and the old setting stays in place.
Usage notes
- It affects
dns.lookup()only.dns.resolve*()returns what the DNS server sent. Everything built onlookup(), includingnet,httpandfetch, follows the setting. - The command-line flag does the same:
node --dns-result-order=ipv4first app.js. TheNODE_OPTIONSenvironment variable can carry it too, which is handy in containers. - A per-call
orderwins.dns.lookup(host, { order: 'ipv4first' })overrides the default for that call; the olderverbatimboolean option is deprecated in its favor. ipv6firstwas added later than the other two (Node 22.1 and 20.13 and later); check your runtime if you target older versions.- Fix servers, not only clients. If
localhostfails, make your server listen on both stacks or on::, instead of forcing the whole process to prefer IPv4. - Happy Eyeballs softens the problem. Since Node 20
net.connect()tries several addresses in turn (autoSelectFamily), so a wrong first answer costs a short delay instead of a failure. - Call it early. Set the order at startup, before connections are made; already-open sockets are not affected.
- It is process-wide, including code inside your dependencies, so libraries should not call it.