Debugging DNS Issues: A Developer's Practical Troubleshooting Guide

Why DNS Issues Are So Frustrating

DNS problems are uniquely painful: they are often intermittent, can take minutes to hours to propagate, and the error messages — "site can't be reached," "NXDOMAIN," "connection timed out" — rarely point to the actual root cause.

This guide walks through the most common DNS failure modes and the exact commands to diagnose each one.

The DNS Resolution Chain

Before debugging, understand what happens when you type a domain into your browser:

1. Browser cache — checked first (TTL from previous lookup)
2. OS resolver cache — /etc/hosts and system DNS cache
3. Recursive resolver — usually your ISP or a public resolver (8.8.8.8)
4. Root nameservers — 13 root server clusters worldwide
5. TLD nameservers — .com, .io, .dev nameservers
6. Authoritative nameserver — your domain registrar or DNS provider

A failure at any step produces different symptoms. The goal is to identify which layer broke.

Common DNS Record Types

Diagnostic Tools

dig — The Gold Standard

# Basic A record lookup
dig heolab.dev A

# Query a specific nameserver
dig @8.8.8.8 heolab.dev A

# Full trace (walk the resolution chain)
dig +trace heolab.dev

# Short answer only
dig +short heolab.dev

# Check all record types
dig heolab.dev ANY

nslookup — Windows-Friendly Alternative

nslookup heolab.dev
nslookup -type=MX heolab.dev
nslookup heolab.dev 1.1.1.1   # Use Cloudflare resolver

host — Simple and Fast

host heolab.dev
host -t MX heolab.dev

Common Issues and Fixes

1. NXDOMAIN — Domain Does Not Exist

Symptom: dig returns NXDOMAIN (Non-Existent Domain).

Causes:

• Domain not registered or expired
• Typo in the domain name
• DNS records deleted by accident
• Nameserver change still propagating

Diagnosis:

# Check if the domain resolves from multiple resolvers
dig @8.8.8.8 yourdomain.com     # Google
dig @1.1.1.1 yourdomain.com     # Cloudflare
dig @9.9.9.9 yourdomain.com     # Quad9

# If all three return NXDOMAIN, the domain truly has no records
# If only one returns NXDOMAIN, it may be a resolver cache issue

2. SERVFAIL — Nameserver Error

Symptom: SERVFAIL status code from dig.

Causes:

• Authoritative nameserver is down
• DNSSEC validation failure
• Zone file misconfiguration

Diagnosis:

# Check who the authoritative NS is
dig NS yourdomain.com

# Query the authoritative NS directly
dig @ns1.yourregistrar.com yourdomain.com

# Check DNSSEC
dig +dnssec yourdomain.com

3. Slow Resolution / Timeouts

Symptom: dig takes 5+ seconds or returns ;; connection timed out.

Causes:

• Authoritative nameserver is unreachable
• TTL set too high (stale cache after a migration)
• Recursive resolver is slow

Fix:

# Measure query time
dig +stats yourdomain.com | grep "Query time"

# Lower TTL before a planned migration (do this 24-48h in advance)
# Change TTL to 300 (5 minutes) well before you switch records

4. Old IP Address Cached After Migration

Symptom: Some users see the old site after you pointed DNS to a new server.

This is always a TTL problem. DNS records are cached for the duration of the TTL.

# Check the current TTL of your A record
dig +nocmd +noall +answer yourdomain.com A
# Look for the number before "IN A" — that's the TTL in seconds

# If TTL is 86400 (24 hours), users could be stuck for up to a day

Best practice: Before any DNS migration, lower your TTL to 60–300 seconds at least 24 hours in advance. After the migration stabilizes, raise it back to 3600–86400.

5. Email Not Delivering (MX Issues)

# Check MX records
dig MX yourdomain.com

# Verify SPF record (prevents email spoofing)
dig TXT yourdomain.com | grep "v=spf1"

# Verify DKIM selector (replace "google" with your selector)
dig TXT google._domainkey.yourdomain.com

# Check DMARC policy
dig TXT _dmarc.yourdomain.com

DNS Propagation Checker

When you update DNS records, propagation can take anywhere from minutes to 48 hours depending on the TTL and resolver caches worldwide. Use HeoLab's DNS Lookup tool to query your domain's records from Cloudflare's DNS-over-HTTPS API in real time — useful for verifying your records are live without waiting for your local cache to expire.

Flush Your Local DNS Cache

# macOS
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

# Linux (systemd-resolved)
sudo systemd-resolve --flush-caches

# Windows
ipconfig /flushdns

# Chrome (clear browser DNS)
# Navigate to: chrome://net-internals/#dns → Clear host cache

Conclusion

Methodical DNS debugging saves hours. Start by querying multiple resolvers to determine if the issue is local or global, then walk the resolution chain with dig +trace to find exactly where resolution fails. Lower TTLs proactively before migrations, and always verify MX, SPF, and DKIM together when troubleshooting email delivery.