DNS | Node.js v22.23.2 Documentation Skip to content Node.js * About this documentation * Usage and example * Assertion testing * Asynchronous context tracking * Async hooks * Buffer * C++ addons * C/C++ addons with Node-API * C++ embedder API * Child processes * Cluster * Command-line options * Console * Crypto * Debugger * Deprecated APIs * Diagnostics Channel * DNS * Domain * Environment Variables * Errors * Events * File system * Globals * HTTP * HTTP/2 * HTTPS * Inspector * Internationalization * Modules: CommonJS modules * Modules: ECMAScript modules * Modules: node:module API * Modules: Packages * Modules: TypeScript * Net * OS * Path * Performance hooks * Permissions * Process * Punycode * Query strings * Readline * REPL * Report * Single executable applications * SQLite * Stream * String decoder * Test runner * Timers * TLS/SSL * Trace events * TTY * UDP/datagram * URL * Utilities * V8 * VM * WASI * Web Crypto API * Web Streams API * Worker threads * Zlib * Code repository and issue tracker Node.js v22.23.2 documentation * Node.js v22.23.2 * Table of contents * DNS * Class: dns.Resolver * Resolver([options]) * resolver.cancel() * resolver.setLocalAddress([ipv4][, ipv6]) * dns.getServers() * dns.lookup(hostname[, options], callback) * Supported getaddrinfo flags * dns.lookupService(address, port, callback) * dns.resolve(hostname[, rrtype], callback) * dns.resolve4(hostname[, options], callback) * dns.resolve6(hostname[, options], callback) * dns.resolveAny(hostname, callback) * dns.resolveCname(hostname, callback) * dns.resolveCaa(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) * dns.reverse(ip, callback) * dns.setDefaultResultOrder(order) * dns.getDefaultResultOrder() * dns.setServers(servers) * DNS promises API * Class: dnsPromises.Resolver * resolver.cancel() * dnsPromises.getServers() * dnsPromises.lookup(hostname[, options]) * dnsPromises.lookupService(address, port) * dnsPromises.resolve(hostname[, rrtype]) * dnsPromises.resolve4(hostname[, options]) * dnsPromises.resolve6(hostname[, options]) * dnsPromises.resolveAny(hostname) * dnsPromises.resolveCaa(hostname) * dnsPromises.resolveCname(hostname) * dnsPromises.resolveMx(hostname) * dnsPromises.resolveNaptr(hostname) * dnsPromises.resolveNs(hostname) * dnsPromises.resolvePtr(hostname) * dnsPromises.resolveSoa(hostname) * dnsPromises.resolveSrv(hostname) * dnsPromises.resolveTlsa(hostname) * dnsPromises.resolveTxt(hostname) * dnsPromises.reverse(ip) * dnsPromises.setDefaultResultOrder(order) * dnsPromises.getDefaultResultOrder() * dnsPromises.setServers(servers) * Error codes * Implementation considerations * dns.lookup() * dns.resolve() , dns.resolve*() , and dns.reverse() * Index * About this documentation * Usage and example * Index * Assertion testing * Asynchronous context tracking * Async hooks * Buffer * C++ addons * C/C++ addons with Node-API * C++ embedder API * Child processes * Cluster * Command-line options * Console * Crypto * Debugger * Deprecated APIs * Diagnostics Channel * DNS * Domain * Environment Variables * Errors * Events * File system * Globals * HTTP * HTTP/2 * HTTPS * Inspector * Internationalization * Modules: CommonJS modules * Modules: ECMAScript modules * Modules: node:module API * Modules: Packages * Modules: TypeScript * Net * OS * Path * Performance hooks * Permissions * Process * Punycode * Query strings * Readline * REPL * Report * Single executable applications * SQLite * Stream * String decoder * Test runner * Timers * TLS/SSL * Trace events * TTY * UDP/datagram * URL * Utilities * V8 * VM * WASI * Web Crypto API * Web Streams API * Worker threads * Zlib * Code repository and issue tracker * Other versions * 26.x * 25.x * 24.x LTS * 23.x * 22.x LTS * 21.x * 20.x * 19.x * 18.x * 17.x * 16.x * 15.x * 14.x * 13.x * 12.x * 11.x * 10.x * 9.x * 8.x * 7.x * 6.x * 5.x * 4.x * 0.12.x * 0.10.x * Options * View on single page * View as JSON * Edit on GitHub Table of contents * DNS * Class: dns.Resolver * Resolver([options]) * resolver.cancel() * resolver.setLocalAddress([ipv4][, ipv6]) * dns.getServers() * dns.lookup(hostname[, options], callback) * Supported getaddrinfo flags * dns.lookupService(address, port, callback) * dns.resolve(hostname[, rrtype], callback) * dns.resolve4(hostname[, options], callback) * dns.resolve6(hostname[, options], callback) * dns.resolveAny(hostname, callback) * dns.resolveCname(hostname, callback) * dns.resolveCaa(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) * dns.reverse(ip, callback) * dns.setDefaultResultOrder(order) * dns.getDefaultResultOrder() * dns.setServers(servers) * DNS promises API * Class: dnsPromises.Resolver * resolver.cancel() * dnsPromises.getServers() * dnsPromises.lookup(hostname[, options]) * dnsPromises.lookupService(address, port) * dnsPromises.resolve(hostname[, rrtype]) * dnsPromises.resolve4(hostname[, options]) * dnsPromises.resolve6(hostname[, options]) * dnsPromises.resolveAny(hostname) * dnsPromises.resolveCaa(hostname) * dnsPromises.resolveCname(hostname) * dnsPromises.resolveMx(hostname) * dnsPromises.resolveNaptr(hostname) * dnsPromises.resolveNs(hostname) * dnsPromises.resolvePtr(hostname) * dnsPromises.resolveSoa(hostname) * dnsPromises.resolveSrv(hostname) * dnsPromises.resolveTlsa(hostname) * dnsPromises.resolveTxt(hostname) * dnsPromises.reverse(ip) * dnsPromises.setDefaultResultOrder(order) * dnsPromises.getDefaultResultOrder() * dnsPromises.setServers(servers) * Error codes * Implementation considerations * dns.lookup() * dns.resolve() , dns.resolve*() , and dns.reverse() DNS # Stability: 2 - Stable Source Code: lib/dns.js The node:dns module enables name resolution. For example, use it to look up IP addresses of host names. Although named for the Domain Name System (DNS) , it does not always use the DNS protocol for lookups. dns.lookup() uses the operating system facilities to perform name resolution. It may not need to perform any network communication. To perform name resolution the way other applications on the same system do, use dns.lookup() . import dns from 'node:dns' ; dns. lookup ( 'example.org' , ( err, address, family ) => { console . log ( 'address: %j family: IPv%s' , address, family); }); // address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6 const dns = require ( 'node:dns' ); dns. lookup ( 'example.org' , ( err, address, family ) => { console . log ( 'address: %j family: IPv%s' , address, family); }); // address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6 copy All other functions in the node:dns module connect to an actual DNS server to perform name resolution. They will always use the network to perform DNS queries. These functions do not use the same set of configuration files used by dns.lookup() (e.g. /etc/hosts ). Use these functions to always perform DNS queries, bypassing other name-resolution facilities. import dns from 'node:dns' ; dns. resolve4 ( 'archive.org' , ( err, addresses ) => { if (err) throw err; console . log ( `addresses: ${ JSON .stringify(addresses)} ` ); addresses. forEach ( ( a ) => { dns. reverse (a, ( err, hostnames ) => { if (err) { throw err; } console . log ( `reverse for ${a} : ${ JSON .stringify(hostnames)} ` ); }); }); }); const dns = require ( 'node:dns' ); dns. resolve4 ( 'archive.org' , ( err, addresses ) => { if (err) throw err; console . log ( `addresses: ${ JSON .stringify(addresses)} ` ); addresses. forEach ( ( a ) => { dns. reverse (a, ( err, hostnames ) => { if (err) { throw err; } console . log ( `reverse for ${a} : ${ JSON .stringify(hostnames)} ` ); }); }); }); copy See the Implementation considerations section for more information. Class: dns.Resolver # Added in: v8.3.0 An independent resolver for DNS requests. Creating a new resolver uses the default server settings. Setting the servers used for a resolver using resolver.setServers() does not affect other resolvers: import { Resolver } from 'node:dns' ; const resolver = new Resolver (); resolver. setServers ([ '4.4.4.4' ]); // This request will use the server at 4.4.4.4, independent of global settings. resolver. resolve4 ( 'example.org' , ( err, addresses ) => { // ... }); const { Resolver } = require ( 'node:dns' ); const resolver = new Resolver (); resolver. setServers ([ '4.4.4.4' ]); // This request will use the server at 4.4.4.4, independent of global settings. resolver. resolve4 ( 'example.org' , ( err, addresses ) => { // ... }); copy The following methods from the node:dns module are available: * resolver.getServers() * resolver.resolve() * resolver.resolve4() * resolver.resolve6() * resolver.resolveAny() * resolver.resolveCaa() * resolver.resolveCname() * resolver.resolveMx() * resolver.resolveNaptr() * resolver.resolveNs() * resolver.resolvePtr() * resolver.resolveSoa() * resolver.resolveSrv() * resolver.resolveTlsa() * resolver.resolveTxt() * resolver.reverse() * resolver.setServers() Resolver([options]) # History Version Changes v16.7.0, v14.18.0 The options object now accepts a tries option. v12.18.3 The constructor now accepts an options object. The single supported option is timeout . v8.3.0 Added in: v8.3.0 Create a new resolver. * options <Object> * timeout <integer> Query timeout in milliseconds, or -1 to use the default timeout. * tries <integer> The number of tries the resolver will try contacting each name server before giving up. Default: 4 * maxTimeout <integer> The max retry timeout, in milliseconds. Default: 0 , disabled. resolver.cancel() # Added in: v8.3.0 Cancel all outstanding DNS queries made by this resolver. The corresponding callbacks will be called with an error with code ECANCELLED . resolver.setLocalAddress([ipv4][, ipv6]) # Added in: v15.1.0, v14.17.0 * ipv4 <string> A string representation of an IPv4 address. Default: '0.0.0.0' * ipv6 <string> A string representation of an IPv6 address. Default: '::0' The resolver instance will send its requests from the specified IP address. This allows programs to specify outbound interfaces when used on multi-homed systems. If a v4 or v6 address is not specified, it is set to the default and the operating system will choose a local address automatically. The resolver will use the v4 local address when making requests to IPv4 DNS servers, and the v6 local address when making requests to IPv6 DNS servers. The rrtype of resolution requests has no impact on the local address used. dns.getServers() # Added in: v0.11.3 * Returns: <string[]> Returns an array of IP address strings, formatted according to RFC 5952 , that are currently configured for DNS resolution. A string will include a port section if a custom port is used. [ '8.8.8.8' , '2001:4860:4860::8888' , '8.8.8.8:1053' , '[2001:4860:4860::8888]:1053' , ] copy dns.lookup(hostname[, options], callback) # History Version Changes v22.1.0 The verbatim option is now deprecated in favor of the new order option. v18.4.0 For compatibility with node:net , when passing an option object the family option can be the string 'IPv4' or the string 'IPv6' . v18.0.0 Passing an invalid callback to the callback argument now throws ERR_INVALID_ARG_TYPE instead of ERR_INVALID_CALLBACK . v17.0.0 The verbatim options defaults to true now. v8.5.0 The verbatim option is supported now. v1.2.0 The all option is supported now. v0.1.90 Added in: v0.1.90 * hostname <string> * options <integer> | <Object> * family <integer> | <string> The record family. Must be 4 , 6 , or 0 . For backward compatibility reasons, 'IPv4' and 'IPv6' are interpreted as 4 and 6 respectively. The value 0 indicates that either an IPv4 or IPv6 address is returned. If the value 0 is used with { all: true } (see below), either one of or both IPv4 and IPv6 addresses are returned, depending on the system's DNS resolver. Default: 0 . * hints <number> One or more supported getaddrinfo flags . Multiple flags may be passed by bitwise OR ing their values. * all <boolean> When true , the callback returns all resolved addresses in an array. Otherwise, returns a single address. Default: false . * order <string> When verbatim , the resolved addresses are return unsorted. When ipv4first , the resolved addresses are sorted by placing IPv4 addresses before IPv6 addresses. When ipv6first , the resolved addresses are sorted by placing IPv6 addresses before IPv4 addresses. Default: verbatim (addresses are not reordered). Default value is configurable using dns.setDefaultResultOrder() or --dns-result-order . * verbatim <boolean> When true , the callback receives IPv4 and IPv6 addresses in the order the DNS resolver returned them. When false , IPv4 addresses are placed before IPv6 addresses. This option will be deprecated in favor of order . When both are specified, order has higher precedence. New code should only use order . Default: true (addresses are not reordered). Default value is configurable using dns.setDefaultResultOrder() or --dns-result-order . * callback <Function> * err <Error> * address <string> A string representation of an IPv4 or IPv6 address. * family <integer> 4 or 6 , denoting the family of address , or 0 if the address is not an IPv4 or IPv6 address. 0 is a likely indicator of a bug in the name resolution service used by the operating system. Resolves a host name (e.g. 'nodejs.org' ) into the first found A (IPv4) or AAAA (IPv6) record. All option properties are optional. If options is an integer, then it must be 4 or 6 – if options is not provided, then either IPv4 or IPv6 addresses, or both, are returned if found. With the all option set to true , the arguments for callback change to (err, addresses) , with addresses being an array of objects with the properties address and family . On error, err is an Error object, where err.code is the error code. Keep in mind that err.code will be set to 'ENOTFOUND' not only when the host name does not exist but also when the lookup fails in other ways such as no available file descriptors. dns.lookup() does not necessarily have anything to do with the DNS protocol. The implementation uses an operating system facility that can associate names with addresses and vice versa. This implementation can have subtle but important consequences on the behavior of any Node.js program. Please take some time to consult the Implementation considerations section before using dns.lookup() . Example usage: import dns from 'node:dns' ; const options = { family : 6 , hints : dns. ADDRCONFIG | dns. V4MAPPED , }; dns. lookup ( 'example.org' , options, ( err, address, family ) => console . log ( 'address: %j family: IPv%s' , address, family)); // address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6 // When options.all is true, the result will be an Array. options. all = true ; dns. lookup ( 'example.org' , options, ( err, addresses ) => console . log ( 'addresses: %j' , addresses)); // addresses: [{"address":"2606:2800:21f:cb07:6820:80da:af6b:8b2c","family":6}] const dns = require ( 'node:dns' ); const options = { family : 6 , hints : dns. ADDRCONFIG | dns. V4MAPPED , }; dns. lookup ( 'example.org' , options, ( err, address, family ) => console . log ( 'address: %j family: IPv%s' , address, family)); // address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6 // When options.all is true, the result will be an Array. options. all = true ; dns. lookup ( 'example.org' , options, ( err, addresses ) => console . log ( 'addresses: %j' , addresses)); // addresses: [{"address":"2606:2800:21f:cb07:6820:80da:af6b:8b2c","family":6}] copy If this method is invoked as its util.promisify() ed version, and all is not set to true , it returns a Promise for an Object with address and family properties. Supported getaddrinfo flags # History Version Changes v13.13.0, v12.17.0 Added support for the dns.ALL flag. The following flags can be passed as hints to dns.lookup() . * dns.ADDRCONFIG : Limits returned address types to the types of non-loopback addresses configured on the system. For example, IPv4 addresses are only returned if the current system has at least one IPv4 address configured. * dns.V4MAPPED : If the IPv6 family was specified, but no IPv6 addresses were found, then return IPv4 mapped IPv6 addresses. It is not supported on some operating systems (e.g. FreeBSD 10.1). * dns.ALL : If dns.V4MAPPED is specified, return resolved IPv6 addresses as well as IPv4 mapped IPv6 addresses. dns.lookupService(address, port, callback) # History Version Changes v18.0.0 Passing an invalid callback to the callback argument now throws ERR_INVALID_ARG_TYPE instead of ERR_INVALID_CALLBACK . v0.11.14 Added in: v0.11.14 * address <string> * port <number> * callback <Function> * err <Error> * hostname <string> e.g. example.com * service <string> e.g. http Resolves the given address and port into a host name and service using the operating system's underlying getnameinfo implementation. If address is not a valid IP address, a TypeError will be thrown. The port will be coerced to a number. If it is not a legal port, a TypeError will be thrown. On an error, err is an Error object, where err.code is the error code. import dns from 'node:dns' ; dns. lookupService ( '127