Skip to content
Tutorials Center
My learning

Topics

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

The Node.js dns/promises module

Reference for node:dns/promises: promise versions of lookup, resolve, reverse and Resolver, with async/await patterns for parallel lookups and fallbacks.

node:dns/promises offers the whole DNS API as functions that return promises, so you can use await instead of callbacks. It is also available as dns.promises on the regular node:dns module. The two APIs behave the same; only the way results are delivered differs.

The main difference you will notice is in return values. Callback functions receive several arguments, such as (err, address, family). A promise can only resolve to one value, so lookup() resolves to an object { address, family } and lookupService() to { hostname, service }.

NODE
import dns from 'node:dns/promises';

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

Try it

Node.js The same module in two places

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 Parallel lookups and fallbacks

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
import dns from 'node:dns/promises';   // or: import { lookup } from 'node:dns/promises'
const dnsViaCallbackModule = (await import('node:dns')).promises;
Export Resolves to
lookup(hostname[, options]) { address, family }, or an array of those with all: true
lookupService(address, port) { hostname, service }
resolve(hostname[, rrtype]) records of the requested type (default 'A')
resolve4(), resolve6(), resolveAny(), resolveCaa(), resolveCname(), resolveMx(), resolveNaptr(), resolveNs(), resolvePtr(), resolveSoa(), resolveSrv(), resolveTlsa(), resolveTxt() the record shapes described on dns.resolve()
reverse(ip) an array of host names
getServers() / setServers(servers) the default resolver's server list (sync)
getDefaultResultOrder() / setDefaultResultOrder(order) the default result order (sync)
Resolver the promise-returning dns.Resolver class

Errors: promises reject with the same error objects as the callback API: code, syscall, hostname. Argument validation errors (ERR_INVALID_ARG_TYPE, ERR_INVALID_ARG_VALUE) are thrown synchronously for some functions, notably resolve() with a bad record type, so keep calls inside try blocks.

Usage notes

  • getServers(), setServers(), getDefaultResultOrder() and setDefaultResultOrder() are synchronous even on the promises module. They return plain values or undefined.
  • Do not mix up the result shape. Code that destructures [address, family] from the callback style must use { address, family } here.
  • lookup() is still thread-pool based. Many parallel lookups queue behind the four default threads; resolve*() calls do not use the pool.
  • No AbortSignal support. To time out a slow query, use a Resolver with a small timeout, race against timers/promises, or call resolver.cancel().
  • Unhandled rejections end the process. A lookup you forget to await or .catch() and that fails will crash a default Node process, so attach handlers.
  • Prefer the promise API in new code. It composes with Promise.all(), try/catch and async functions, and it avoids callback nesting.