Skip to content
Tutorials Center
My learning

Topics

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.

NODE
import dns from 'node:dns';

dns.setDefaultResultOrder('ipv4first');
console.log(dns.getDefaultResultOrder()); // 'ipv4first'

Try it

Node.js Reading and changing the order

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 Per-call order and sorted results

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
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 on lookup(), including net, http and fetch, follows the setting.
  • The command-line flag does the same: node --dns-result-order=ipv4first app.js. The NODE_OPTIONS environment variable can carry it too, which is handy in containers.
  • A per-call order wins. dns.lookup(host, { order: 'ipv4first' }) overrides the default for that call; the older verbatim boolean option is deprecated in its favor.
  • ipv6first was 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 localhost fails, 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.