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().
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.
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
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
localhostand hosts-file entries do not resolve.resolve()asks DNS servers only. Usedns.lookup()for names the operating system knows.- Servers come from the system configuration (for example
/etc/resolv.conf). Change them for this process withdns.setServers(), or give one consumer its own settings withdns.Resolver. - Results are not sorted for you.
resolveMx()returns records in the order the server sent them; sort bypriorityyourself 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 asresolve(host, 'MX')but reads better and is easier to search for. resolveAny()is unreliable. Many servers refuse or truncateANYqueries (it was largely deprecated for abuse reasons). Ask for the types you need.- Retries and timeouts belong to the
Resolveroptions (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.
Related
dns.lookup(),dns.reverse(),dns.Resolver,dns/promises- Lessons: UDP and DNS