Skip to content
Tutorials Center
My learning

Topics

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

Node.js dns.resolve() method

Reference for dns.resolve() and resolve4/resolveMx/resolveTxt in Node.js: query DNS servers directly for A, AAAA, MX, TXT and other record types.

dns.resolve() sends a real DNS query and returns the records of one type for a name. Unlike dns.lookup(), it never touches the hosts file or the operating system resolver: Node uses its bundled c-ares library to talk to the DNS servers directly, without blocking the thread pool.

Use it when you need more than an address: mail servers (MX), text records (TXT, used for SPF and domain verification), name servers (NS), service locators (SRV) and so on. Each record type also has a shortcut function such as dns.resolve4() or dns.resolveMx().

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

const addresses = await dns.resolve('example.org', 'A');
// ['203.0.113.10']

Try it

Real DNS needs a network, which the example runner does not have. So these examples start a tiny DNS server on 127.0.0.1 (about 30 lines, using node:dgram) and point a Resolver at it. The code you use in production is identical, apart from the setServers() line.

Node.js Records by type

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 Errors for missing names and records

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.resolve(hostname[, rrtype], callback)
dnsPromises.resolve(hostname[, rrtype]): Promise<string[] | object[]>

dns.resolve4(hostname[, options], callback)   // options: { ttl: boolean }
dns.resolve6(hostname[, options], callback)   // options: { ttl: boolean }
dns.resolveAny(hostname, callback)
dns.resolveCaa(hostname, callback)
dns.resolveCname(hostname, callback)
dns.resolveMx(hostname, callback)
dns.resolveNaptr(hostname, callback)
dns.resolveNs(hostname, callback)
dns.resolvePtr(hostname, callback)
dns.resolveSoa(hostname, callback)
dns.resolveSrv(hostname, callback)
dns.resolveTlsa(hostname, callback)
dns.resolveTxt(hostname, callback)
Name Description
hostname The name to query, for example example.org.
rrtype Record type as a string: 'A' (default), 'AAAA', 'ANY', 'CAA', 'CNAME', 'MX', 'NAPTR', 'NS', 'PTR', 'SOA', 'SRV', 'TLSA' or 'TXT'.
options.ttl For resolve4() and resolve6(): return { address, ttl } objects instead of strings.
callback Called with (err, records).

Returns: the shape depends on the record type.

Type Result
A, AAAA, CNAME, NS, PTR array of strings
MX array of { priority, exchange } (Node 24 also adds type: 'MX')
TXT array of arrays of strings (one inner array per record; each string is one chunk of up to 255 bytes)
SRV array of { priority, weight, port, name }
SOA one object: nsname, hostmaster, serial, refresh, retry, expire, minttl
CAA array of objects with critical and a property such as issue or iodef
NAPTR, TLSA arrays of objects (see the Node.js docs for the field names)
ANY array of objects, each with a type field plus the fields of that type

Errors: the error code is one of the constants on dns: dns.NODATA (name exists but has no record of that type), dns.NOTFOUND (no such name), dns.TIMEOUT, dns.CONNREFUSED, dns.SERVFAIL, dns.REFUSED, dns.BADNAME, dns.CANCELLED and a few more. The error also carries syscall (for example queryA) and hostname. An unknown rrtype throws ERR_INVALID_ARG_VALUE immediately, even from the promise API, so wrap the call in try/catch rather than relying on .catch().

Usage notes

  • localhost and hosts-file entries do not resolve. resolve() asks DNS servers only. Use dns.lookup() for names the operating system knows.
  • Servers come from the system configuration (for example /etc/resolv.conf). Change them for this process with dns.setServers(), or give one consumer its own settings with dns.Resolver.
  • Results are not sorted for you. resolveMx() returns records in the order the server sent them; sort by priority yourself before picking a mail server.
  • TXT records are chunked. Join the inner arrays when you need the full text: records.map((chunks) => chunks.join('')).
  • Use the shortcut methods for clarity. resolveMx() is the same query as resolve(host, 'MX') but reads better and is easier to search for.
  • resolveAny() is unreliable. Many servers refuse or truncate ANY queries (it was largely deprecated for abuse reasons). Ask for the types you need.
  • Retries and timeouts belong to the Resolver options (tries, timeout); the default module-level functions use c-ares defaults. A dead server can make a call take many seconds.
  • resolveTlsa() is newer (Node 22.15 and 23.9 and later); check your runtime before relying on it.