Skip to content
Tutorials Center
My learning

Topics

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

Node.js dns.lookup() method

Reference for dns.lookup() in Node.js: resolve a host name with the operating system resolver, choose IPv4 or IPv6, get all addresses, and handle errors.

dns.lookup() turns a host name such as localhost or example.org into an IP address. It asks the operating system to do the work, by calling the same getaddrinfo routine that every other program on the machine uses. That means it honors the hosts file, the system's search domains and its resolver configuration.

This is the function Node itself uses when you call net.connect(), http.request() or fetch() with a host name. It is not a pure DNS client: it can return answers that never touched a DNS server (for example a line from /etc/hosts). To send real DNS queries and read record types, use dns.resolve() instead.

NODE
import dns from 'node:dns';

dns.lookup('localhost', { family: 4 }, (err, address, family) => {
  console.log(address, family); // 127.0.0.1 4
});

Try it

Node.js Callback and promise forms

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 All addresses and options

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.lookup(hostname[, options], callback)
// callback(err, address, family)           when options.all is false
// callback(err, addresses)                 when options.all is true

dnsPromises.lookup(hostname[, options]): Promise<{ address: string, family: 4 | 6 }>
dnsPromises.lookup(hostname, { all: true }): Promise<Array<{ address: string, family: 4 | 6 }>>
Name Description
hostname The name to resolve. An IP address string is returned unchanged.
options An integer (4, 6 or 0) as a shortcut for family, or an object (below).
options.family 4, 6 or 0 (any, the default). The strings 'IPv4' and 'IPv6' are accepted too.
options.hints Flags for getaddrinfo, combined with `
options.all true returns every address instead of the first one.
options.order 'verbatim', 'ipv4first' or 'ipv6first'. Overrides the default from dns.setDefaultResultOrder().
options.verbatim Older boolean form of order; prefer order.
callback Required for the callback API.

Returns: nothing for the callback form; a promise for the dns/promises form.

Errors: the error object has code set to a getaddrinfo code such as ENOTFOUND (no such name) or EAI_AGAIN (a temporary failure, often no network), plus hostname and syscall: 'getaddrinfo'. Invalid arguments throw synchronously from the callback form with ERR_INVALID_ARG_VALUE or ERR_INVALID_ARG_TYPE; the promise form rejects with the same codes.

Usage notes

  • It runs on the libuv thread pool, not on the event loop. Each call occupies one of four threads by default (UV_THREADPOOL_SIZE). A burst of slow lookups can delay file-system and crypto work that shares the pool.
  • It is not DNS-only. /etc/hosts, mDNS and NSS plugins may answer. This is why localhost works even without a network, and why results can differ from dig or nslookup.
  • Order matters. Since Node 17 the default result order is verbatim: addresses come back in the order the resolver returned them, so an IPv6 address may come first. Use order: 'ipv4first' or a family filter if your server only listens on IPv4.
  • No caching. Node does not cache answers. The OS or a local resolver might, but a hot code path that connects often should reuse sockets (keep-alive agents) instead of looking up every time.
  • Prefer all: true for connecting. With every address in hand you can try the next one when the first fails. net.connect() does this for you when autoSelectFamily is on (the default since Node 20).
  • Not interchangeable with resolve. lookup() accepts IP literals and consults the hosts file; resolve*() does neither, and it fails on localhost unless the DNS server knows it.