Frustrated with `.local` domains breaking on macOS Sonoma after browser updates? I’ll walk you through why it’s happening and provide three solid fixes, from a quick patch to the right long-term solution for you and your team.

So, Your `.local` Dev Environment Just Broke on macOS. Let’s Talk.

I remember a 2 AM incident a few years back. We were pushing a critical hotfix for our main payment gateway. Everything looked perfect in staging. We push to prod, pop the champagne… and then the alerts start screaming. Half our internal monitoring dashboards, the ones we desperately needed to see if the fix worked, were dead. The culprit? A junior engineer, bless his heart, had hardcoded a grafana.local address in a config file. It worked on his machine, but nowhere else. This new Safari and macOS Sonoma issue with .local domains feels exactly like that, except now the problem isn’t one person’s config—it’s the entire OS fighting you.

The “Why”: What Changed and Why is `.local` Suddenly a Problem?

Let’s get this straight: .local was never truly ours to use. It’s a special-use top-level domain (TLD) reserved for Multicast DNS (mDNS), which is the technology behind Apple’s Bonjour service. It’s how your Mac finds printers and other devices on your local network automatically, without a central DNS server.

For years, developers have “borrowed” .local for local development environments (I’ve done it, you’ve done it, we’ve all done it). It just worked. However, with recent updates in macOS Sonoma and stricter browser standards (like in Safari Technology Preview 234), the operating system is enforcing this rule more aggressively. When your browser tries to resolve api.myapp.local, macOS is now correctly prioritizing its mDNS function, assuming you’re looking for a Bonjour-enabled device, not the Docker container running on your localhost. The result is a timeout or a DNS resolution error that leaves you staring at a blank page.

The Fixes: From a Quick Patch to a Proper Cure

Alright, enough theory. You’ve got a deadline and your local environment is down. Let’s get you back up and running. I’ve got three ways to tackle this, from the quick-and-dirty to the one you should have been doing all along.

1. The Quick Fix: The Classic /etc/hosts Entry

This is the fastest way to get back to work. You’re going to manually tell your machine exactly where to find your .local domain, bypassing mDNS entirely. It’s a Band-Aid, but it’s a good one.

Just open up your /etc/hosts file with root permissions:

sudo nano /etc/hosts

And add a line at the bottom mapping your local domain to your loopback address (127.0.0.1):

# Existing hosts file entries...
127.0.0.1 localhost
255.255.255.255 broadcasthost
::1             localhost

# Project-specific entries
127.0.0.1 my-project.local
127.0.0.1 api.my-project.local

Save the file, and you might need to flush your local DNS cache for it to take effect immediately.

sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

Warning: This fix is only on your machine. It’s a workaround, not a solution. Your new team member will run into the exact same issue, and you’ll have to explain this all over again. Don’t commit projects that rely on manual hosts file entries.

2. The Permanent Fix: Stop Using .local Entirely

This is the one I’m going to tell my team to do. It’s time to rip the Band-Aid off. The .local TLD is reserved. Fighting the operating system is a losing battle. We need to migrate our development environments to a different TLD.

Here are some solid, community-accepted alternatives:

TLD	Why it’s a good choice
.test	Reserved by the IETF specifically for testing. It’s guaranteed to never be a public TLD. This is my top recommendation.
.localhost	Also reserved and guaranteed to always point back to 127.0.0.1. Excellent for simple projects, but can be less flexible if you need multiple subdomains pointing to different container IPs.
.example	Reserved for documentation and examples. Perfectly safe to use.

Migrating is straightforward. Go into your project’s configuration—whether it’s a Docker Compose file, a webpack config, or your Nginx/Caddy proxy settings—and do a find-and-replace for .local with .test. It’s a one-time pain that solves the problem for everyone on the team, forever.

3. The ‘Nuclear’ Option: Create a Custom macOS Resolver

Okay, let’s say you’re in a situation where you absolutely cannot change the .local domain. Maybe it’s a massive legacy project or a client requirement you can’t push back on. There’s a more robust, system-level way to force macOS to resolve .local domains using standard DNS without touching the hosts file.

You can create a custom resolver configuration for the .local TLD. This tells macOS: “Hey, for any domain ending in .local, forget mDNS and just use this specific nameserver.”

First, create the resolver directory if it doesn’t exist:

sudo mkdir -p /etc/resolver

Now, create a new file inside that directory named local (the name must match the TLD you’re targeting):

sudo nano /etc/resolver/local

Inside this new file, add the following line to point all .local lookups to your localhost resolver:

nameserver 127.0.0.1

Save the file. This change takes effect almost immediately. Now, any request for some-service.local will be sent directly to 127.0.0.1, where your local proxy (like Traefik, Caddy, or Nginx Proxy Manager) can handle it properly.

Pro Tip: This is a powerful technique, but it’s still a local machine configuration. It’s better than the hosts file because it applies to the entire TLD, but it doesn’t fix the root issue. Use this when you’re cornered, but plan your escape to the permanent fix (Option 2) as soon as you can.

Hopefully, this clears things up and gets your code compiling again. Now, go update those old project READMEs before you forget.

– Darian Vance
Senior DevOps Engineer & Lead Cloud Architect, TechResolve

---

🤖 Frequently Asked Questions