Node.js DNS: lookup vs. resolve

WHY IT EXISTS: Networked applications need to turn hostnames into routable addresses and inspect DNS records for routing, validation, and discovery. Node.js exposes these capabilities through the DNS module so JavaScript code can resolve names without shelling out to system tools. The module separates system-level address resolution from direct DNS record queries because operating systems and DNS servers serve different purposes.

THE MENTAL MODEL: Think of the DNS module as two doors into a building. The dns.lookup door asks the operating system for an IP address the same way any other program on the machine would, using getaddrinfo. The dns.resolve door sends a DNS protocol question to a nameserver and returns raw records like MX, TXT, or SRV. One door talks to the OS; the other talks to the network.

HOW IT WORKS: The module exposes dns.lookup with optional flags and a callback, alongside dns.lookupService for address-to-service mapping. For direct queries, it provides dns.resolve, dns.resolve4, dns.resolve6, dns.resolveAny, dns.resolveCname, dns.resolveCaa, dns.resolveMx, dns.resolveNaptr, dns.resolveNs, dns.resolvePtr, dns.resolveSoa, dns.resolveSrv, dns.resolveTlsa, dns.resolveTxt, and dns.reverse for PTR lookups. Each of these families has its own implementation considerations. You can create independent resolver instances via the dns.Resolver class, which accepts options and exposes cancel and setLocalAddress. Global behavior is configurable through dns.setServers, dns.getServers, dns.setDefaultResultOrder, and dns.getDefaultResultOrder. A parallel promises API under dnsPromises mirrors the callback surface.

WHEN TO USE IT: Use dns.lookup when you simply need an IPv4 or IPv6 address to open a connection, since it uses getaddrinfo. Use dns.resolveMx when validating email domains, dns.resolveTxt when reading verification records, and dns.resolveSrv when locating service endpoints. Use dns.Resolver when you need isolated resolution state, custom local addresses, or the ability to cancel in-flight queries.

WHEN NOT TO USE IT: Do not use dns.lookup if you need non-address records like TXT or MX, because it is built around getaddrinfo and does not return them. Do not use the dns.resolve family if you require the behavior of the system getaddrinfo path, because the two have separate implementation considerations. Avoid mixing the two families without understanding their distinct error codes and configuration.

ONE CANONICAL EXAMPLE: An Express application that validates incoming email domains before signup calls dns.resolveMx to confirm the domain accepts mail. It avoids dns.lookup because an IP address alone does not prove mail configuration. If the query hangs, the application uses a dns.Resolver instance and calls resolver.cancel to abandon the request.