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 }.
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
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
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()andsetDefaultResultOrder()are synchronous even on the promises module. They return plain values orundefined.- 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
AbortSignalsupport. To time out a slow query, use aResolverwith a smalltimeout, race againsttimers/promises, or callresolver.cancel(). - Unhandled rejections end the process. A lookup you forget to
awaitor.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/catchandasyncfunctions, and it avoids callback nesting.