Skip to main content
The node:dns module enables name resolution for looking up IP addresses of host names.

​
Import

import dns from 'node:dns';
// or
const dns = require('node:dns');

​
DNS Resolution Methods

There are two types of DNS resolution in Node.js:
  1. dns.lookup() - Uses the operating system’s facilities (e.g., /etc/hosts)
  2. dns.resolve*() - Connects directly to DNS servers

​
dns.lookup()

​
Basic Usage

import dns from 'node:dns';

dns.lookup('example.org', (err, address, family) => {
  console.log('address: %j family: IPv%s', address, family);
  // address: "93.184.216.34" family: IPv4
});

​
With Options

dns.lookup('example.org', {
  family: 6,
  hints: dns.ADDRCONFIG | dns.V4MAPPED
}, (err, address, family) => {
  console.log('address: %j family: IPv%s', address, family);
});

​
Get All Addresses

const options = {
  all: true
};

dns.lookup('example.org', options, (err, addresses) => {
  console.log('addresses:', addresses);
  // [
  //   { address: '93.184.216.34', family: 4 },
  //   { address: '2606:2800:220:1:248:1893:25c8:1946', family: 6 }
  // ]
});

​
Parameters

  • hostname
  • options
    • family 4, 6, or 0 (both)
    • hints getaddrinfo flags
    • all Return all addresses
    • order 'ipv4first', 'ipv6first', or 'verbatim'
  • callback
    • err
    • address
    • family

​
DNS Resolve Methods

​
dns.resolve4()

Resolve IPv4 addresses (A records). 
dns.resolve4('example.org', (err, addresses) => {
  if (err) throw err;
  console.log('addresses:', addresses);
  // ['93.184.216.34']
});

​
With TTL Information

dns.resolve4('example.org', { ttl: true }, (err, addresses) => {
  console.log(addresses);
  // [
  //   { address: '93.184.216.34', ttl: 21600 }
  // ]
});

​
dns.resolve6()

Resolve IPv6 addresses (AAAA records). 
dns.resolve6('example.org', (err, addresses) => {
  if (err) throw err;
  console.log('IPv6 addresses:', addresses);
});

​
dns.resolveMx()

Resolve mail exchange records. 
dns.resolveMx('example.org', (err, addresses) => {
  if (err) throw err;
  console.log('MX records:', addresses);
  // [
  //   { priority: 10, exchange: 'mx.example.com' },
  //   { priority: 20, exchange: 'mx2.example.com' }
  // ]
});

​
dns.resolveTxt()

Resolve text records. 
dns.resolveTxt('example.org', (err, records) => {
  if (err) throw err;
  console.log('TXT records:', records);
  // [
  //   ['v=spf1 include:_spf.example.com ~all']
  // ]
});

​
dns.resolveCname()

Resolve canonical name records. 
dns.resolveCname('www.example.org', (err, addresses) => {
  if (err) throw err;
  console.log('CNAME records:', addresses);
  // ['example.org']
});

​
dns.resolveNs()

Resolve name server records. 
dns.resolveNs('example.org', (err, addresses) => {
  if (err) throw err;
  console.log('NS records:', addresses);
  // ['ns1.example.com', 'ns2.example.com']
});

​
dns.resolveSrv()

Resolve service records. 
dns.resolveSrv('_http._tcp.example.org', (err, addresses) => {
  if (err) throw err;
  console.log('SRV records:', addresses);
  // [
  //   {
  //     priority: 10,
  //     weight: 5,
  //     port: 80,
  //     name: 'server.example.org'
  //   }
  // ]
});

​
dns.resolveSoa()

Resolve start of authority record. 
dns.resolveSoa('example.org', (err, address) => {
  if (err) throw err;
  console.log('SOA record:', address);
  // {
  //   nsname: 'ns.example.com',
  //   hostmaster: 'root.example.com',
  //   serial: 2013101809,
  //   refresh: 10000,
  //   retry: 2400,
  //   expire: 604800,
  //   minttl: 3600
  // }
});

​
dns.resolvePtr()

Resolve pointer records (reverse DNS). 
dns.resolvePtr('34.216.184.93.in-addr.arpa', (err, addresses) => {
  if (err) throw err;
  console.log('PTR records:', addresses);
});

​
dns.resolveCaa()

Resolve certification authority authorization records. 
dns.resolveCaa('example.org', (err, records) => {
  if (err) throw err;
  console.log('CAA records:', records);
  // [
  //   { critical: 0, iodef: 'mailto:[email protected]' },
  //   { critical: 128, issue: 'pki.example.com' }
  // ]
});

​
Reverse DNS Lookup

dns.reverse('8.8.8.8', (err, hostnames) => {
  if (err) throw err;
  console.log('Reverse DNS:', hostnames);
  // ['dns.google']
});

​
DNS Server Configuration

​
Get DNS Servers

const servers = dns.getServers();
console.log('DNS servers:', servers);
// ['8.8.8.8', '8.8.4.4']

​
Set DNS Servers

dns.setServers([
  '8.8.8.8',
  '2001:4860:4860::8888',
  '8.8.8.8:1053',
  '[2001:4860:4860::8888]:1053'
]);

​
Class: dns.Resolver

Create independent DNS resolvers with custom settings.

​
Creating a Resolver

import { Resolver } from 'node:dns';

const resolver = new Resolver();
resolver.setServers(['4.4.4.4']);

resolver.resolve4('example.org', (err, addresses) => {
  console.log(addresses);
});

​
Resolver Options

const resolver = new Resolver({
  timeout: 5000,      // Query timeout in milliseconds
  tries: 4,           // Number of tries per name server
  maxTimeout: 10000   // Max retry timeout
});

​
Resolver Methods

​
resolver.setLocalAddress([ipv4][, ipv6])

Set the IP addresses to use when making DNS requests. 
resolver.setLocalAddress('192.168.1.100');

​
resolver.cancel()

Cancel all outstanding DNS queries. 
resolver.cancel();

​
DNS Promises API

​
Using Promises

import { promises as dnsPromises } from 'node:dns';

try {
  const addresses = await dnsPromises.resolve4('example.org');
  console.log('Addresses:', addresses);
} catch (err) {
  console.error('DNS error:', err);
}

​
Lookup with Promises

import { promises as dnsPromises } from 'node:dns';

const { address, family } = await dnsPromises.lookup('example.org');
console.log('address: %j family: IPv%s', address, family);

​
Resolver with Promises

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

const resolver = new Resolver();
resolver.setServers(['1.1.1.1', '8.8.8.8']);

const addresses = await resolver.resolve4('example.org');
console.log(addresses);

​
Error Handling

​
Common Error Codes

  • ENOTFOUND - Domain name not found
  • ENODATA - No data returned from DNS
  • ETIMEOUT - DNS query timed out
  • ECONNREFUSED - Connection refused
  • ECANCELLED - Query was cancelled

​
Error Handling Example

dns.lookup('nonexistent.invalid', (err, address) => {
  if (err) {
    if (err.code === 'ENOTFOUND') {
      console.error('Domain not found');
    } else if (err.code === 'ETIMEOUT') {
      console.error('DNS query timed out');
    } else {
      console.error('DNS error:', err);
    }
    return;
  }
  console.log('Address:', address);
});

​
Setting Default Result Order

import dns from 'node:dns';

// Set default ordering for dns.lookup()
dns.setDefaultResultOrder('ipv4first');
// or
dns.setDefaultResultOrder('ipv6first');
// or
dns.setDefaultResultOrder('verbatim');

const order = dns.getDefaultResultOrder();
console.log('Current order:', order);

​
Example: Complete DNS Tool

import dns from 'node:dns';
import { promisify } from 'node:util';

const lookup = promisify(dns.lookup);
const resolve4 = promisify(dns.resolve4);
const resolve6 = promisify(dns.resolve6);
const resolveMx = promisify(dns.resolveMx);
const reverse = promisify(dns.reverse);

async function dnsLookupAll(hostname) {
  console.log(`\nDNS Lookup for: ${hostname}\n`);
  
  try {
    // Basic lookup
    const { address, family } = await lookup(hostname);
    console.log('Primary IP:', address, `(IPv${family})`);
    
    // IPv4 addresses
    const ipv4 = await resolve4(hostname);
    console.log('IPv4 Addresses:', ipv4);
    
    // IPv6 addresses
    try {
      const ipv6 = await resolve6(hostname);
      console.log('IPv6 Addresses:', ipv6);
    } catch (err) {
      console.log('IPv6: Not available');
    }
    
    // MX records
    try {
      const mx = await resolveMx(hostname);
      console.log('MX Records:', mx);
    } catch (err) {
      console.log('MX: Not available');
    }
    
    // Reverse DNS
    try {
      const hostnames = await reverse(address);
      console.log('Reverse DNS:', hostnames);
    } catch (err) {
      console.log('Reverse DNS: Not available');
    }
    
  } catch (err) {
    console.error('Error:', err.message);
  }
}

// Usage
await dnsLookupAll('example.org');

​
Example: DNS Caching

import dns from 'node:dns';
import { promisify } from 'node:util';

const lookup = promisify(dns.lookup);

class DNSCache {
  constructor(ttl = 60000) {
    this.cache = new Map();
    this.ttl = ttl;
  }
  
  async lookup(hostname) {
    const cached = this.cache.get(hostname);
    
    if (cached && Date.now() < cached.expires) {
      return cached.address;
    }
    
    const { address } = await lookup(hostname);
    
    this.cache.set(hostname, {
      address,
      expires: Date.now() + this.ttl
    });
    
    return address;
  }
  
  clear() {
    this.cache.clear();
  }
}

// Usage
const dnsCache = new DNSCache(300000); // 5 minutes
const address = await dnsCache.lookup('example.org');

​
Performance Considerations

  1. Use dns.lookup() for simple hostname resolution - It’s faster and uses the OS cache
  2. Use dns.resolve*() for DNS-specific queries - Direct DNS server communication
  3. Implement DNS caching - Reduce DNS queries for frequently accessed domains
  4. Handle errors gracefully - DNS failures are common
  5. Use Promise API - Cleaner async/await syntax

​
Best Practices

// DO: Use promises for cleaner code
const { address } = await dnsPromises.lookup('example.org');

// DO: Handle errors
try {
  const addresses = await dnsPromises.resolve4('example.org');
} catch (err) {
  if (err.code === 'ENOTFOUND') {
    // Handle missing domain
  }
}

// DO: Use custom resolvers for specific DNS servers
const resolver = new Resolver();
resolver.setServers(['1.1.1.1']);

// AVOID: Synchronous operations (not available in dns module)
// AVOID: Too many concurrent DNS requests