DNS for Developers: Records, Propagation, Troubleshooting

DNS is the phone book of the internet, but for developers it's often the thing that breaks a deploy at 2 a.m. and leaves you refreshing a browser tab wondering why your changes aren't live. Understanding how DNS actually works — the record types, the caching layers, and the tools that let you see what's really happening — turns those mysterious outages into five-minute fixes. This guide covers what you need to know in practice.

How DNS Resolution Actually Works

When someone types example.com into a browser, a chain of lookups happens before a single byte of your app is served:

The browser and OS check their local caches.
If there's no cached answer, the query goes to a recursive resolver (often your ISP's, or something like 8.8.8.8 or 1.1.1.1).
The resolver walks the hierarchy: root servers → TLD servers (.com, .org) → your domain's authoritative nameservers.
The authoritative nameserver returns the record, which gets cached at every hop on the way back.

That caching is the source of most confusion. When you "change DNS," you're updating the authoritative record instantly — but every resolver that already has the old answer will keep serving it until its cached copy expires.

The Records You'll Actually Use

There are dozens of DNS record types, but developers touch a handful repeatedly:

A — Maps a hostname to an IPv4 address. example.com → 93.184.216.34.
AAAA — The same thing for IPv6.
CNAME — An alias pointing one name at another name. www.example.com → example.com. A CNAME cannot coexist with other records on the same name, which is why you can't put a CNAME on a root/apex domain in classic DNS (some providers offer "ALIAS" or "ANAME" flattening to work around this).
MX — Mail exchange records, with a priority number. Lower priority wins. These route email, not web traffic — a common mixup when someone changes A records and panics that email broke (it usually didn't).
TXT — Arbitrary text. Used heavily for domain verification, SPF, DKIM, and DMARC email-authentication policies.
NS — Delegates a zone to its authoritative nameservers.
SOA — Start of Authority; holds zone metadata including serial numbers and default TTLs.
CAA — Specifies which certificate authorities may issue certs for your domain. Worth setting for security.
SRV — Defines the location (host + port) of specific services.

A quick note on TTL

Every record carries a Time To Live in seconds — how long resolvers may cache it. A TTL of 3600 means one hour. This single number governs how fast your changes propagate. Set it low (300 seconds) before a planned migration so caches expire quickly, then raise it back afterward to reduce lookup load.

Understanding Propagation

"DNS propagation" is a slightly misleading phrase. Nothing actively pushes your change outward. Instead, old cached answers simply expire and get replaced on the next lookup. The maximum time this takes is bounded by:

The TTL of the old record (the big one).
Resolvers that ignore TTLs and cache aggressively (some ISPs do this).
Your registrar's propagation to TLD servers, when you change nameservers rather than records (this can genuinely take up to 24–48 hours because TLD glue updates are slower).

Practical rules that save you grief:

Lower the TTL a day in advance. If your record has a 24-hour TTL and you drop it to 5 minutes today, the old 24-hour value is still cached for up to a day. Plan ahead.
Changing a record (A/CNAME) is fast — bounded by TTL. Changing nameservers is slow — bounded by TLD propagation.
Your machine lies to you. Local OS and browser caches make it look unpropagated long after it's live globally. Always verify with a tool, not a browser refresh.

Troubleshooting Toolkit

Learn these command-line tools; they'll answer the vast majority of your DNS questions.

dig — your primary instrument

# Basic A record lookup
dig example.com A

# Just the answer, no noise
dig +short example.com

# Query a specific resolver (bypass your local cache)
dig @1.1.1.1 example.com

# See the full delegation chain
dig +trace example.com

# Check the TTL currently being served
dig example.com | grep -A1 "ANSWER SECTION"

The +trace option is gold when a domain won't resolve — it walks from the root down and shows you exactly where the chain breaks.

nslookup — the cross-platform fallback

Available everywhere including Windows. Less detailed than dig but fine for a quick check:

nslookup example.com
nslookup -type=MX example.com

host — the quick one-liner

host example.com
host -t TXT example.com

Checking propagation globally

Because caching is regional, a record can be live in one country and stale in another. Query multiple public resolvers to sample different regions:

dig @8.8.8.8 example.com +short   # Google
dig @1.1.1.1 example.com +short   # Cloudflare
dig @9.9.9.9 example.com +short   # Quad9

If they agree, you're propagated. If they disagree, you're mid-flight — wait for the TTL. Web tools that check dozens of global resolvers at once are also handy for a visual confirmation.

Flushing your local cache

When the world shows the new record but your machine doesn't:

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

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

# Windows
ipconfig /flushdns

Common Failure Modes

"It works for me but not for the customer." Classic caching split. They're on a resolver still serving the old record. Confirm with dig @their-resolver and wait out the TTL.

Root domain won't take a CNAME. You're hitting the CNAME-at-apex restriction. Use your provider's ALIAS/ANAME flattening or an A record instead.

Email broke after a DNS change. Check your MX and TXT (SPF/DKIM/DMARC) records specifically. A/AAAA changes don't touch mail routing, but if you moved nameservers, you may have dropped records that weren't migrated.

New nameservers, still resolving old host for two days. Nameserver changes propagate via TLD servers and are legitimately slow. This is normal; wait it out and verify with dig +trace.

SSL certificate errors after migration. Often your CAA record blocks the new CA, or a proxy (like Cloudflare) is intercepting. Check dig example.com CAA.

Best Practices

Keep TTLs moderate (3600s) for stable records; drop them temporarily before planned changes.
Set a CAA record to lock down certificate issuance.
Configure SPF, DKIM, and DMARC properly if you send email — deliverability depends on it.
Document your zone. A version-controlled zone file or infrastructure-as-code (Terraform) beats clicking around a web console.
Never test propagation from a browser. Use dig.

FAQ

How long does DNS propagation really take? For record changes (A, CNAME, TXT), it's bounded by the TTL — often minutes to a few hours. For nameserver changes, allow up to 24–48 hours because TLD-level updates are slower.

Why does my site work on my phone but not my laptop? Different devices use different resolvers and caches. Your phone on cellular data hits a different DNS path than your laptop on office Wi-Fi. Flush your local cache and query with dig to compare.

Can I speed up propagation? Not retroactively — you can't recall answers already cached. But you can lower the TTL well before a planned change so caches expire quickly when the switch happens.

What's the difference between a CNAME and an A record? An A record points a name directly at an IP address. A CNAME points a name at another name, requiring a second lookup to resolve the final IP. Use A records at the apex; CNAMEs are convenient for subdomains that should follow another host.

Why can't I put a CNAME on my root domain? The DNS spec forbids a CNAME coexisting with the other records (SOA, NS) that must exist at the apex. Providers work around this with ALIAS/ANAME records that flatten to A records automatically.

My record looks correct but the site still won't load — is it DNS? Confirm resolution with dig +short. If the right IP comes back, DNS is fine and the problem is elsewhere (web server, firewall, or TLS). DNS troubleshooting stops the moment you get the correct answer from an authoritative source.

DNS rewards patience and the right tools. Once you internalize that everything is caching and TTLs, the "mysterious" delays become predictable — and dig becomes the first thing you reach for instead of the last.