scutil --dns Lied to Me

One of my Mac minis stopped being able to find github.com. Not “the network is down” — brew update, git pull, plain curl https://github.com all failed with Could not resolve host, while the four identical minis next to it on the same shelf were fine.

These minis are my agent workers: each runs Claude Code sessions doing real jobs, and they talk to the outside world over USB Ethernet adapters I swap around when one dies. So “can’t resolve a hostname” means “can’t clone repos, can’t install anything, can’t do its job.” But here’s the part that made me waste an hour: I could still SSH into the box just fine. It looked online.

Quick gloss for anyone who isn’t a network person: DNS is the phone book that turns a name like github.com into the actual numeric address your machine dials. This mini had a working phone line but a blank phone book. SSH worked because I was connecting to it by its number on the local network — no phone book needed.

So I did what every macOS answer on the internet tells you: I ran scutil --dns, the standard “show me my DNS config” command. It showed a perfectly good DNS server. Reachable. Configured. I sat there confused — the tool said everything was fine, and nothing was fine.

The trap is that scutil --dns merges every network interface into one happy-looking list. That good DNS entry belonged to a secondary interface — a leftover adapter that had a scoped resolver. The interface actually carrying my traffic, the one holding the default route, had been handed an empty DNS list by DHCP when I swapped its USB adapter. The phone book on the line I was actually using was blank. scutil just didn’t bother to tell me which line was which.

The fix that survives reboots and future adapter swaps is to stop trusting DHCP for DNS entirely and pin my LAN gateway as the resolver on every network service the mini knows about.

Finding the real resolver and pinning it give me the detail

Don’t trust the aggregate view. Ask which interface owns the default route, then ask that interface for its DNS:

# which interface actually carries traffic?
route -n get default | grep interface   # e.g. en6

# map that BSD name to a service name, then check ITS resolver
networksetup -listallhardwareports
networksetup -getdnsservers "USB 10/100/1000 LAN"   # -> "There aren't any..."

That empty answer is the real bug — invisible in scutil --dns. Pin your gateway across all enabled services so a swap can’t rebreak it:

GATEWAY=$(route -n get default | awk '/gateway/{print $2}')
networksetup -listallnetworkservices | tail -n +2 | while read svc; do
  networksetup -setdnsservers "$svc" "$GATEWAY"
done

Now every service resolves through the LAN gateway regardless of what DHCP offers.

The general lesson I took: when a host resolves nothing, diagnose the resolver on the default-route interface specifically, never the merged view. Tools that aggregate across interfaces are lying to you by omission — they show you a working config that belongs to the wrong card. Find the line you’re actually talking on, and check that phone book.