Fixing DNS Resolution Problems in macOS Apps From the Terminal

DNS failures are silent saboteurs. Your app makes a request, the spinner turns, and nothing comes back. No clear error, no obvious cause. If you have spent an afternoon chasing a bug that turned out to be a broken DNS resolver or a misconfigured search domain, you know exactly how frustrating that gets. The good news is that macOS ships with a solid set of Terminal tools that let you peel back every layer of name resolution and pinpoint the problem fast.

Why DNS Failures Quietly Break macOS App Development

Name resolution is so fundamental that most development tools assume it simply works. When it does not, the error messages almost never say “DNS failed.” Instead you get connection timeouts, TLS handshake errors, or vague “network unavailable” responses. This indirection is what makes DNS bugs so hard to catch without deliberate tooling.

The problem compounds in local development. You might be running a reverse proxy, a VPN for a client network, or a custom /etc/hosts entry for a staging domain. Any one of these can silently redirect or block a hostname without giving your app any meaningful feedback. Your code looks fine. Your server logs show nothing. The resolver is where everything falls apart.

macOS also caches DNS aggressively. That caching is good for everyday browsing, but it creates a specific class of bug during development: your code is correct, the server configuration is updated, but your Mac is still handing out an old IP address from a response it received hours ago.

Reading the Terminal Warning Signs

Before reaching for any specific tool, pay attention to how your app’s failure presents itself. A few patterns point strongly toward DNS:

• Requests to external APIs that time out in your app but work fine in a browser on the same machine
• Staging or preview domains that resolve correctly in curl but fail inside the Xcode simulator
• Webhook endpoints that cannot be reached from a third-party service even though your local server is running and responsive

Each of these has a DNS dimension worth checking. The timeout-in-app-but-works-in-browser pattern often means your app is using a different resolver, or a system network extension is intercepting requests. The simulator failure is a known edge case where the iOS simulator can inherit a different DNS configuration than the host Mac. Webhook failures from external services bring in a different concern entirely: what does the outside world see when it tries to reach your machine?

Using dig to Trace DNS Queries Step by Step

dig is the most precise DNS tool on macOS. It bypasses the system resolver entirely and queries a DNS server directly, which means it gives you authoritative answers rather than cached ones.

The simplest use is dig example.com. This queries your default nameserver and returns the full response, including the answer section, the authority section, and the query time. That last number matters. A query time over 300ms on a local network suggests the resolver is struggling or unreachable.

To query a specific server, add it after an @ sign: dig @8.8.8.8 example.com. This lets you compare what Google’s public DNS returns against what your corporate VPN’s resolver returns. When the answers differ, you have found the split. Your machine is resolving to a different IP than the rest of the world, which explains why your API calls behave differently depending on which network you are on.

The +trace flag is worth knowing for harder problems. Running dig +trace example.com walks the full resolution chain from root servers down to the authoritative nameserver. This is the right move when you suspect a misconfigured delegation or a domain that has partially propagated after a DNS change. According to the authoritative DNS standard, a conforming resolver must cache negative responses too, meaning a failed lookup can persist just as long as a successful one. This is why flushing the cache matters even when a domain “should” be working by now.

nslookup for Sanity-Checking Specific Record Types

nslookup is older than dig and less precise in its output, but it has one practical advantage: its interactive mode. Run nslookup with no arguments and you get a prompt. You can change the server, the query type, and the domain without retyping a full command each time. This makes it useful for rapid iteration when you are testing multiple record types against the same domain.

For most debugging tasks, a direct call works fine. Running nslookup -type=TXT example.com returns TXT records, which is what you need when verifying SPF, DKIM, or domain ownership tokens that third-party services require. These are common failure points during webhook setup and App Store Connect domain verification.

The key difference between nslookup and dig is that nslookup does go through the system resolver by default. If your system resolver is the problem, nslookup will reflect that problem while dig can bypass it. Use both tools together to tell the difference between a resolver issue and a propagation issue. Agreement between them points to propagation. Disagreement points to your local resolver configuration.

What scutil --dns Tells You About Your Mac’s Resolver

scutil --dns is the command that most developers skip, and it is often the most revealing one. It prints the complete DNS configuration that macOS is actually using at the system level, including every search domain, every nameserver, and the order in which they apply.

Run it and look at the output carefully. You will likely see multiple resolver configurations stacked on top of each other. One applies to your Wi-Fi interface, another to your VPN tunnel, another to a specific domain suffix. macOS applies these in order, and the order matters. If a VPN has injected a resolver for all queries rather than just for its own domain, every hostname your app touches goes through that VPN’s DNS, whether you intended that or not.

Search domains are another common culprit. A search domain like corp.example.com tells macOS to append that suffix to unqualified hostnames. If your app queries a short hostname like api, macOS might expand it to api.corp.example.com before sending the query. That expansion is invisible to your app but changes the lookup entirely. Spotting it in scutil --dns output takes about ten seconds and saves hours of head-scratching.

Verifying Your Mac’s Network Identity for API and Certificate Debugging

Some debugging scenarios require you to know what your machine looks like from the outside. This comes up more often than most developers expect. An API with IP allowlisting, a webhook that filters by source address, or a certificate validation service that checks a domain’s A record against the requesting IP all depend on what external servers see when your Mac makes a request.

Terminal tools give you the local view. Running ifconfig or checking scutil --nwi shows your local and potentially your NAT addresses, but those are not what a remote server receives. Your router performs network address translation, so the IP your Mac thinks it has is almost never the IP that hits an external endpoint.

This is where a browser-based check complements your Terminal workflow rather than replacing it. Pulling up what is my IP from a browser tab on the same machine confirms the public address your requests will carry. Cross-reference that against the IP your DNS records point to, and you can immediately confirm whether your domain’s A record matches the address you are actually sending traffic from. This matters when debugging certificate validation failures that only surface under specific network conditions, or when a staging API key is locked to a particular IP range.

The workflow is straightforward: run your DNS checks in Terminal, then flip to a browser tab to verify the public-facing address. You do not need to leave your development environment or spin up a separate tool on another machine. Two minutes of checking saves a support ticket to the API provider.

Flushing Caches and Resetting the Resolver

Once you have identified the problem, the fix is often a cache flush. macOS has changed the flush command across versions, but on current macOS releases the two-step approach covers both caching layers:

• Run sudo dscacheutil -flushcache to clear the DNS cache held by Directory Services
• Follow it immediately with sudo killall -HUP mDNSResponder to restart the mDNSResponder daemon, which maintains its own separate cache

Both steps together are necessary. The first clears the lookup cache. The second reloads the active resolver configuration, picking up any changes you have made to network settings, VPN configuration, or /etc/hosts. Doing only one of the two often leaves stale data behind and makes it look like your flush did nothing.

If a VPN or network extension is causing the problem, the fix may require disconnecting, flushing, and reconnecting in the right order. Some VPN clients re-inject their resolver settings on reconnect, which means you need to verify with scutil --dns after each step rather than assuming the flush persisted through the reconnection.

For persistent problems tied to a specific domain, checking your /etc/hosts file is worth the thirty seconds it takes. A manual override in that file takes priority over everything else, including your DNS configuration. If a hostname was hardcoded there during earlier testing and never removed, that entry will keep returning the wrong address no matter how many times you flush the cache or restart the resolver.

From Terminal Output to a Working App

DNS debugging has a reputation for being opaque, but the tools macOS provides make the process surprisingly direct when you work through them in a logical sequence. dig gives you raw resolver output that bypasses local caching. nslookup handles fast record lookups against the system resolver for comparison. scutil --dns exposes the full system configuration including VPN and search domain interference that neither of the other tools reveals. A browser-based IP check fills in the one gap the Terminal cannot easily address: what external servers actually see when your requests arrive.

Working through these tools in sequence turns a vague network failure into a specific, fixable problem. The request goes through, the certificate validates, the webhook fires. And next time a DNS issue surfaces during development, you will know exactly where to start.