DNS Troubleshooting Guide

## DNS Troubleshooting Guide DNS issues range from the trivially simple (flushing a local cache) to the deeply subtle (split-brain DNS or propagation timing conflicts). This guide gives you a systematic approach and concrete commands for diagnosing the most common problems. ## Diagnostic Toolkit Before diving into specific issues, familiarize yourself with these tools: **`dig`** — the primary DNS diagnostic tool on Linux/macOS: ```bash dig example.com A # A record dig example.com MX # MX records dig example.com TXT # TXT records dig example.com NS # Nameservers dig -x 203.0.113.10 # Reverse DNS dig @8.8.8.8 example.com A # Query specific resolver ``` **`nslookup`** — available on Windows and macOS: ```bash nslookup example.com nslookup -type=MX example.com nslookup example.com 8.8.8.8 # Use Google's resolver ``` **`host`** — simple reverse/forward lookups: ```bash host example.com host 203.0.113.10 ``` **Online tools:** - [whatsmydns.net](https://www.whatsmydns.net) — global propagation checker - [dnschecker.org](https://dnschecker.org) — similar multi-location view - Google Admin Toolbox — email and MX diagnostics ## Problem 1: Website Unreachable After DNS Change **Symptoms:** Browser shows "This site can't be reached" or "DNS_PROBE_FINISHED_NXDOMAIN." **Step 1: Query your authoritative nameserver directly.** ```bash # Find your nameservers dig example.com NS # Query the authoritative nameserver directly dig @ns1.yourprovider.com example.com A ``` If the authoritative server returns the correct IP, the record is correctly set and you are waiting for DNS Propagation — not a configuration error. **Step 2: Check what your resolver sees.** ```bash dig @8.8.8.8 example.com A dig @1.1.1.1 example.com A ``` If one resolver shows the new IP and another shows the old one, propagation is in progress. If both show the old IP, the TTL has not expired yet. **Step 3: Flush your local cache.** ```bash # macOS sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder # Windows ipconfig /flushdns # Linux (systemd-resolved) sudo systemctl restart systemd-resolved ``` Then retry the lookup. If it resolves correctly after flushing, the issue was a stale local cache — not a server problem. ## Problem 2: Email Not Delivering After MX Change **Symptoms:** Sent emails bounce, or recipients report not receiving mail. **Step 1: Verify MX records.** ```bash dig example.com MX ``` Check that the MX values match exactly what your email provider specified. Common issues: wrong hostnames, IP addresses in MX fields (invalid), or old MX records still present alongside new ones. **Step 2: Verify the MX hostname resolves.** ```bash dig mail.example.com A ``` The hostname in your MX record must have an A record. If it returns `NXDOMAIN`, mail delivery will fail for senders who look it up. **Step 3: Check SPF, DKIM, DMARC.** ```bash dig example.com TXT | grep spf dig _dmarc.example.com TXT dig mail._domainkey.example.com TXT ``` Missing or malformed SPF/DKIM/DMARC records cause delivery failures or spam-folder placement. See TXT Records: SPF, DKIM, and DMARC Explained for correct format. **Step 4: Test with mail-tester.com.** Send an email to the address shown on mail-tester.com and review the full authentication report. ## Problem 3: SSL Certificate Error After DNS Change **Symptoms:** Browser shows "Your connection is not private" or SSL certificate warnings. **Root cause:** SSL certificates are domain-verified. After changing DNS, the certificate provisioning service needs to re-verify your domain. This typically happens automatically but takes 5–30 minutes. **Step 1: Check whether DNS points to the correct server.** ```bash dig example.com A ``` If the IP is correct, wait 10–15 minutes and try again — most SSL providers (Let's Encrypt, Cloudflare) auto-renew certificates after DNS changes. **Step 2: If using Cloudflare.** Ensure SSL mode is set to Full or Full (Strict), not Flexible. Flexible mode causes SSL errors on sites with server-side SSL configured. **Step 3: If using a dedicated SSL certificate.** Manually trigger a certificate renewal or re-issue through your certificate provider. Let's Encrypt: `sudo certbot renew --force-renewal`. ## Problem 4: Record Change Not Taking Effect **Symptoms:** You updated a DNS record but it still returns the old value everywhere. **Step 1: Confirm the change was saved.** Log into your DNS provider and verify the record shows the new value. It is surprisingly common to save a change on the wrong record or accidentally click away without saving. **Step 2: Check TTL.** ```bash dig example.com A +ttlunits ``` If the TTL was 86400 (24 hours) before your change, resolvers may hold the old value for up to 24 hours. There is nothing to do but wait. **Step 3: Verify the correct nameservers are active.** ```bash dig example.com NS +short ``` If these are not your current DNS provider's nameservers, you may be editing records at the wrong provider. Changes to the inactive provider have no effect. ## Problem 5: Domain Shows "NXDOMAIN" (Does Not Exist) **Symptoms:** `dig` returns `NXDOMAIN` — the domain appears to not exist. **Possible causes:** 1. **Domain expired.** Check registration status with WHOIS Lookup Tool. 2. **Nameservers not set.** At registrar, nameservers may be blank or set to deleted servers. 3. **Zone not active.** The DNS provider may require activating the zone separately. 4. **Propagation delay.** Newly registered domains take minutes to appear globally. ```bash # Check if the root zone knows about your domain dig example.com NS @a.gtld-servers.net ``` If the root returns your nameservers, the domain is delegated correctly. If it returns nothing, the domain registration or NS delegation has a problem. ## Problem 6: Different Results from Different Locations **Symptoms:** Works on your home network, broken on mobile data; or works in some countries, not others. **This is normal during propagation.** Different resolvers have different cache states. Use [whatsmydns.net](https://www.whatsmydns.net) to check from 30+ global locations at once. If propagation has completed (several hours after a TTL-appropriate wait) but results still differ by location, suspect: - **Anycast routing differences:** Some CDNs return different IPs based on geography. This is intentional. - **Geographic DNS policies:** Your DNS provider may return different records based on the querier's location (split-horizon or geo-DNS). - **Stale resolver caches:** A specific ISP resolver may not have refreshed. Use `@8.8.8.8` and `@1.1.1.1` as reference points — if they agree, the issue is an outlier resolver, not your DNS. ## Problem 7: Email Authentication Failures (SPF/DKIM/DMARC) **Symptoms:** Outgoing email lands in spam. Email headers show `DKIM=fail` or `SPF=fail`. **Step 1:** Confirm the TXT records are correctly published: ```bash dig example.com TXT | grep spf dig mail._domainkey.example.com TXT dig _dmarc.example.com TXT ``` **Step 2:** Check SPF lookup count. If your SPF record includes many `include:` statements, you may exceed the 10-lookup limit. Use a SPF flattening service. **Step 3:** Verify DKIM selector. The `mail` in `mail._domainkey.example.com` is the selector. If your email provider uses a different selector (e.g. `google`, `s1`, `k1`), use their exact selector when querying. For a complete walkthrough, see TXT Records: SPF, DKIM, and DMARC Explained. ## Next Steps - DNS During Domain Migration — avoid common DNS change mistakes from the start - Understanding DNS Propagation — understand why changes are not instant - Setting Up DNS for Your Domain — build a correctly configured zone from scratch