Quick Answer
When an application cannot reach an external database, API, or upstream service, engineers often point fingers at the network or firewall. Frequently, however, the culprit is hidden right in the name resolution layer. Effective dns troubleshooting requires moving methodically through every phase of the lookup path—from local system caches and recursive resolvers all the way to authoritative name servers and record TTL configurations. Whether you are debugging sudden production outages or investigating why a staging domain fails to resolve on a newly provisioned server, following a structured methodology eliminates guesswork and pinpoints the exact point of failure.
Quick Answer
How do you troubleshoot DNS? To troubleshoot DNS effectively, start by isolating whether the issue is local or global. First, query the domain locally using tools like dig or nslookup to see what IP address your machine receives. Next, bypass your local and network recursive resolvers by querying the domain's authoritative nameservers directly. If the authoritative server returns the correct record but your local machine fails, the issue stems from an outdated local DNS cache, a misconfigured /etc/resolv.conf file, or an intermediate caching resolver holding stale records. If the authoritative server returns an incorrect record or times out entirely, you must inspect your zone files, registrar configurations, or upstream delegation paths. Understanding this layered traffic flow allows engineers to quickly determine whether a connection failure originates from local operating system settings, recursive resolver timeouts, or upstream record misconfigurations.
DNS Troubleshooting Checklist
Jumping blindly between terminal commands wastes critical time during an incident. A reliable dns troubleshooting workflow relies on a layered diagnostic checklist that proceeds strictly from the bottom of the stack upward. Common mistakes during outages include confusing IP addresses with service ports, treating DNS entries as static mappings that update instantly everywhere, assuming TCP and UDP network behavior are interchangeable when handling large responses, and skipping intermediate layers of the verification chain.
To execute a systematic triage, follow this sequence: verify local resolution behavior, test against trusted public resolvers, inspect authoritative records directly, review Time to Live (TTL) parameters, and safely clear local caches if stale data persists. Each step narrows the pool of potential suspects until the root cause reveals itself.
Verify the Domain
Image Pending
Using dig to inspect DNS query status and server response details.
Why does a domain resolve on one machine but not another? This classic riddle usually points to divergent resolver configurations, local hosts file overrides, or stale operating system caches. To begin isolating the failure, verify the domain from the affected host using command-line diagnostic tools. Avoid relying solely on browser behavior, which introduces extra variables like HTTP proxy settings, TLS handshakes, and browser-internal DNS caches.
Execute a basic query using dig to inspect the response section and the query status:
dig example.com +noall +answer
If dig returns an NXDOMAIN status code, the domain name does not exist in the queried zone, or your resolver cannot reach the parent zone. If it returns SERVFAIL, the upstream resolver encountered a critical failure while trying to fetch the record. For simpler environments where dig is unavailable, nslookup provides a quick alternative:
nslookup example.com
Review the output to ensure the returned IP address matches your expectations. If your local container or virtual machine uses an internal service discovery mechanism like CoreDNS or Consul, verify that your /etc/resolv.conf points to the correct cluster gateway rather than an unreachable external IP.
Query Authoritative Servers
When local lookups disagree with reality, you must bypass recursive resolvers entirely and query the authoritative nameservers directly. Recursive resolvers cache responses for the duration specified by the record's TTL, meaning they can serve outdated data long after you have updated your DNS records at your registrar or cloud provider.
First, find the authoritative nameservers for your domain by querying the parent zone:
dig NS example.com +short
Once you have the list of nameservers (for example, ns1.example-dns.com), query one of them directly using the @ syntax in dig:
dig @ns1.example-dns.com example.com A
This command forces the specific nameserver to evaluate its local zone files and return the answer without consulting any intermediate cache. If this direct query returns the correct IP address while your standard queries return old data, you have confirmed a caching or propagation delay rather than a broken record configuration.
Check Records and TTL
DNS errors frequently stem from syntax mistakes in zone files or misunderstandings about how Time to Live (TTL) values control record propagation. Every DNS record—whether an A record for IPv4, an AAAA record for IPv6, a CNAME for aliasing, or a TXT record for domain verification—must adhere strictly to formatting rules.
Record correctness
Ensuring record correctness requires verifying that hostnames do not end with unintended trailing characters, that IP addresses are formatted without typos, and that CNAME records do not point to root domains where other record types coexist. A common syntax error involves omitting the trailing dot in fully qualified domain names (FQDNs) within zone file definitions, causing the nameserver to automatically append the origin domain twice.
nameservers
Correct nameserver configuration forms the backbone of reliable domain resolution. If your domain's NS records at your domain registrar do not match the NS records declared inside your DNS hosting provider's zone file, resolvers experience delegation inconsistencies. These mismatches cause intermittent resolution failures where requests succeed on some networks and fail on others depending on which nameserver path is chosen.
resolver comparison
Comparing recursive versus authoritative DNS behaviors helps diagnose why high-traffic applications occasionally time out. Recursive resolvers handle client requests by doing all the heavy lifting across the global hierarchy, whereas authoritative servers simply hold the final source-of-truth records for specific zones. During major traffic spikes or DDoS events, overloaded recursive resolvers may drop incoming UDP queries, triggering application-level connection errors even though the underlying authoritative servers remain healthy.
cache
Intermediate caching layers speed up web navigation by storing query responses closer to the end user. However, these caches can also trap stale IP addresses during cloud migrations or failover events. Inspecting cache invalidation timers and verifying that your TTL values were lowered prior to executing an infrastructure migration ensures smooth traffic transitions without downtime.
delegation
Zone delegation mechanics dictate how requests pass from root servers down to top-level domains, authoritative nameservers, and subdomains. A broken referral path—often caused by deleting a child nameserver record at the parent zone level without updating the corresponding glue records—results in complete resolution failure for the entire subdomain.
Compare Resolvers
Differences in resolver behavior frequently explain why a domain resolves cleanly on an engineer's local workstation but fails inside a production Kubernetes cluster or cloud environment. Public resolvers such as Google (8.8.8.8), Cloudflare (1.1.1.1), or Quad9 (9.9.9.9) implement aggressive caching policies, EDNS client subnet passing, and robust security filtering. In contrast, corporate or ISP resolvers may apply outdated caching rules, block specific query types, or suffer from internal routing latency.
To test how different resolvers handle your domain, run explicit queries against multiple public providers:
dig @8.8.8.8 example.com
dig @1.1.1.1 example.com
If 1.1.1.1 returns the correct record while your local ISP resolver returns an error, your local network infrastructure may be caching a poisoned or outdated response. In containerized microservices, explicitly configure your container base images or Kubernetes dnsPolicy settings to use reliable upstream resolvers if your cloud provider's internal DNS service experiences transient degradation.
Flush Cache
When you have confirmed that authoritative records are correct and public resolvers have updated, lingering DNS errors are almost always caused by active local caches on your workstation, operating system, or application runtime. Clearing these caches safely in production environments requires understanding the scope of each caching layer.
On modern Linux distributions utilizing systemd-resolved, you can safely clear the resolver cache without restarting network interfaces:
systemd-resolve --flush-caches
For macOS systems, the cache-clearing command varies across major OS versions; on recent releases, you reset the multicast DNS and unicast cache using:
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder
Avoid blunt troubleshooting methods like completely disabling network interfaces or restarting physical routers unless hardware failure is suspected. Furthermore, be aware that many modern programming language runtimes (such as Java JVM or Node.js) maintain their own internal DNS TTL caches independent of the operating system. If an application continues connecting to an old IP address after you have flushed the OS cache, inspect the application's runtime networking configuration for internal caching parameters.
Common Failure Patterns
Recognizing recurring failure patterns accelerates incident response during critical outages. One frequent pattern is the propagation delay trap, where engineers update a record with a 24-hour TTL and expect global visibility within seconds. Because global recursive resolvers respect the TTL set during the previous lookup, old records persist around the world until that timer expires.
Another prevalent issue involves TCP versus UDP behavior in containerized environments. Standard DNS queries travel over UDP on port 53. However, when a DNS response exceeds 512 bytes—common with DNSSEC signatures, extensive TXT records, or large IPv6 record sets—the server truncates the response. Standard clients then retry the query over TCP. If intermediate stateful firewalls or security groups block TCP port 53 while allowing UDP, applications experience mysterious, intermittent resolution failures whenever response payloads grow too large.
Finally, container networking layers often mask underlying DNS resolution failures. If a container cannot resolve an internal service name, verify that the container runtime's bridge network is forwarding queries to the cluster's DNS pod rather than dropping packets due to strict iptables rules. By methodically stepping through each layer of this diagnostic checklist, developers and DevOps engineers can isolate, diagnose, and resolve even the most elusive DNS anomalies with confidence.
