Skip to content
Tutorials Center
My learning

Topics

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

Node.js dns.Resolver class

Reference for the dns.Resolver class in Node.js: use your own DNS servers, set timeouts and retries, cancel pending queries and isolate settings.

A Resolver is an independent DNS client. It has its own list of servers and its own timeout and retry settings, and it offers the same resolve*() and reverse() methods as the dns module. The module-level functions share one hidden default resolver; creating your own lets you query a specific server (a company DNS server, 1.1.1.1, a test server) without changing global state.

A resolver can also cancel everything that is in flight with cancel(), which the module functions cannot do. Both node:dns and node:dns/promises export a Resolver class: the first reports results in callbacks, the second in promises.

NODE
import { Resolver } from 'node:dns/promises';

const resolver = new Resolver({ timeout: 2000, tries: 2 });
resolver.setServers(['1.1.1.1', '8.8.8.8']);

Try it

Node.js Servers, options and isolation

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 Cancelling pending queries

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
new dns.Resolver([options])
new dnsPromises.Resolver([options])
Option Description
timeout Milliseconds to wait for a reply before retrying. The default -1 uses the c-ares default.
tries How many times each server is tried before giving up. Default 4.

Methods (the promise version returns promises instead of taking callbacks):

Method Description
getServers() Array of strings such as '192.0.2.53' or '198.51.100.53:5353' (port 53 is omitted).
setServers(servers) Replace the server list. Entries are 'address' or 'address:port'; IPv6 with a port is '[2001:db8::53]:5353'. Throws ERR_INVALID_IP_ADDRESS for a bad entry. Do not call it while queries are running.
setLocalAddress([ipv4][, ipv6]) Choose the local address that outgoing queries use.
cancel() Fail every outstanding query with code ECANCELLED.
resolve(), resolve4(), resolve6(), resolveAny(), resolveCaa(), resolveCname(), resolveMx(), resolveNaptr(), resolveNs(), resolvePtr(), resolveSoa(), resolveSrv(), resolveTlsa(), resolveTxt(), reverse() Same as the module functions, see dns.resolve() and dns.reverse().

Errors: queries fail with codes such as ENOTFOUND, ENODATA, ETIMEOUT, ECONNREFUSED and ECANCELLED.

Usage notes

  • A new resolver starts with the system's servers, the same ones dns.getServers() shows. Call setServers() only if you want something different.
  • There is no lookup() on a resolver. dns.lookup() always uses the operating system, so a Resolver cannot change it. To make HTTP clients use your servers, resolve the name yourself and pass a custom lookup function to net.connect() or an agent.
  • Set timeout and tries deliberately. With the defaults a dead server costs many seconds. A short timeout with two tries fails faster and lets the next server answer.
  • Use one resolver per purpose. Sharing a long-lived resolver for a service is cheap; creating one per request is not necessary.
  • cancel() is the only way to stop a query. Promise-based calls do not accept an AbortSignal; cancel the resolver, or race the call against a timer.
  • IPv6 servers work in setServers() and the entries come back from getServers() exactly as stored.
  • dns.setServers() on the module changes the default resolver for the entire process, including servers used by dns.resolve*() calls in your dependencies. Prefer your own Resolver in libraries.