DNS That Resolves on the Host but Not Inside a Container

The gap between your shell's resolver and your container's is bigger than it looks

Contents

nslookup mylab.local works fine from a terminal on the host. The same lookup, run inside a container on that same machine, times out. This is one of those bugs that looks impossible at first glance — it’s the same machine, the same physical network interface, surely the same DNS — and it’s also one of the more common tickets in any thread about self-hosted Docker setups, because the assumption that a container shares its host’s DNS resolution path is wrong in a way that isn’t obvious until you’ve hit it.

This is easy to miss because so much else about a container feels shared with the host — the filesystem layer, the process list you’d see with docker top, even the kernel itself — that assuming DNS is shared too is a reasonable, if wrong, extrapolation. The short version: a container gets its own network namespace, and by default its own resolver configuration, separate from the host’s. What resolves the hostname on your host — systemd-resolved, /etc/hosts, a local DNS cache, mDNS via Avahi — often isn’t reachable, or isn’t even running, from inside that namespace. This post walks through why the split happens and the actual fixes, roughly in order of how often each one turns out to be the cause.

Why the Host and the Container See Different DNS

On a typical Linux host running systemd-resolved, /etc/resolv.conf usually points at 127.0.0.53, a local stub resolver that handles caching, mDNS, and forwarding to your actual upstream DNS servers. That stub resolver is a process bound to the host’s loopback interface. A container, sitting in its own network namespace with its own loopback, cannot reach 127.0.0.53 on the host — loopback addresses don’t cross network namespace boundaries. Docker knows this, and by default rewrites the container’s /etc/resolv.conf to point directly at real upstream resolvers rather than the host’s stub, either by reading through to what systemd-resolved itself forwards to, or falling back to public resolvers if it can’t determine that.

This rewriting is exactly where things go wrong for .local or custom-domain hostnames. If your host resolves mylab.local via mDNS (Avahi) or a local DNS server on your LAN that only your host’s stub resolver is configured to query, and Docker’s rewritten resolv.conf points the container at a public upstream resolver instead, the container will dutifully ask a resolver that has never heard of mylab.local and get nothing back. The host isn’t lying to you about being able to resolve the name; the container genuinely can’t reach the resolver that knows the answer.

A dense tangle of blue, white and red network patch cables hanging in front of a server rack.
Layers of cabling in front of a server rack: each hop between a container and its resolver is another place a lookup can go astray. Photo: Server Rack with Spaghetti-Like Mass of Network Cables by Kim Scarborough from Chicago, IL, CC BY-SA 2.0, via Wikimedia Commons.
1
2
3
4
5
6
7
# on the host
cat /etc/resolv.conf
# nameserver 127.0.0.53  <- systemd-resolved stub, container can't reach this

# inside a container on the same host
docker run --rm alpine cat /etc/resolv.conf
# nameserver 8.8.8.8     <- Docker's fallback, which has never heard of mylab.local

Fix One: Point the Container at a Resolver It Can Actually Reach

The most direct fix is telling Docker explicitly which DNS server to use for the container, rather than relying on the automatic rewrite. If you run a local DNS server on your LAN — a Pi-hole, AdGuard Home, or your router’s own resolver — that’s reachable by IP from the container’s network namespace even when the host’s loopback stub isn’t:

1
2
3
4
5
6
services:
  app:
    image: myapp:latest
    dns:
      - 192.168.1.1      # your LAN's actual DNS server, not the host's loopback stub
      - 1.1.1.1          # fallback for public names

This works because 192.168.1.1 is a real address on the LAN, reachable from any network namespace with a route to that network, unlike 127.0.0.53 which is scoped to the host alone. Setting this at the Compose or daemon level means every container on that host gets a resolver that actually knows about your local names, without needing to fix it per-container after the fact.

Fix Two: Make the Host’s Resolver Actually Reachable

If you’d rather containers use the same resolution logic as the host — including mDNS for .local names — the alternative is exposing a real, reachable DNS listener on the host rather than only the loopback-bound stub. On systems using systemd-resolved, this typically means configuring it to also listen on the Docker bridge interface, or running a small local resolver (dnsmasq, or a container-based one) bound to an address containers can reach, that itself forwards to systemd-resolved or Avahi for .local lookups.

1
2
# check what systemd-resolved is actually bound to
sudo ss -tulnp | grep :53

This is more setup than Fix One and mostly worth it if you specifically need mDNS resolution (device discovery via .local names) to work identically inside containers, rather than just needing a fixed set of local hostnames to resolve — for most homelab cases, a real local DNS server per Fix One is simpler and more robust.

One extra wrinkle worth knowing before you go this route: exposing systemd-resolved on the Docker bridge interface means it’s now reachable from every container on that bridge, which is a wider exposure than a single dns: entry pointing at your existing LAN resolver. If the host also runs anything security-sensitive that assumes the resolver is loopback-only, checking the firewall rules on the bridge interface first avoids quietly widening an attack surface you didn’t mean to touch just to fix a .local lookup.

Why This Bites Homelabs More Than Cloud Deployments

This particular failure is disproportionately a homelab problem rather than a cloud one, and it’s worth understanding why: cloud deployments overwhelmingly resolve services by public DNS names or cloud-provider-internal DNS (like a managed Kubernetes service’s internal zone), both of which any resolver, including Docker’s public-upstream fallback, can answer without help. Homelabs lean heavily on .local mDNS names and router-assigned local DNS specifically because there’s no cloud provider supplying a DNS zone for you — you’re relying on your own LAN’s resolution, which is exactly the thing Docker’s default rewrite bypasses. If you’ve only ever deployed to a cloud provider before setting up a home server, this is a genuinely new failure mode, rather than a Docker bug you’d have hit there too.

Fix Three: Use Docker’s Embedded DNS for Container-to-Container Names

A related but distinct problem: containers on the same user-defined Docker network can resolve each other by container or service name automatically, via Docker’s embedded DNS server at 127.0.0.11 inside the container’s namespace. If that’s failing — one container can’t resolve another by name even though both are clearly running — the usual cause is that they’re not actually on the same user-defined network. Containers on the default bridge network don’t get automatic name-based resolution; only containers on a network you’ve explicitly created (or that Compose creates for you) do.

1
docker network inspect my-project_default | grep -A3 '"Containers"'

If a container you expect to see there is missing, it’s likely still attached only to the default bridge, often because it was started with docker run outside the Compose project rather than as part of it, or because a networks: key was left off its service definition in the compose file.

A second, more subtle version of this trips people up on multi-network setups: a container attached to two user-defined networks resolves other containers on both, but the reverse resolution isn’t automatically symmetric if the two containers don’t actually share a network in common. Listing both containers’ networks side by side with docker inspect and confirming an actual overlap, rather than assuming “they’re both on some network” is enough, resolves this faster than trial and error with restarts.

Fix Four: Set It Once, at the Daemon Level, Instead of Per-Container

If nearly every container on a host needs the same local DNS server, repeating dns: in every Compose file is easy to forget on the next new service. Docker reads a daemon-wide default from /etc/docker/daemon.json, which every container picks up unless it overrides DNS itself:

1
2
3
{
  "dns": ["192.168.1.1", "1.1.1.1"]
}

A restart of the Docker daemon (sudo systemctl restart docker) is required for this to take effect, and it’s worth doing on a maintenance window rather than mid-session, since it briefly stops every running container’s networking. Once set, new containers inherit it automatically, which is the more maintainable version of Fix One for a host running more than a couple of services.

If you’re on Podman rather than Docker, particularly in rootless mode, the same host-versus-container DNS split exists but the default resolver setup differs enough that Docker-specific advice doesn’t always transfer directly. Podman’s rootless networking typically runs through slirp4netns or pasta, each with its own DNS forwarding behaviour, and the equivalent fix is usually setting dns in a containers.conf or directly in the pod/container’s network settings rather than a Docker daemon file. The diagnostic sequence below still applies regardless of which runtime you’re on — confirm connectivity, then confirm which resolver is configured, before assuming the fix from one runtime carries over to the other unchanged.

Troubleshooting: Confirming Which Layer Is Actually Broken

Rather than guessing at the fix, confirm where in the chain the failure actually is:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# does the container reach the network at all?
docker run --rm alpine ping -c2 1.1.1.1

# can it resolve a public name via whatever resolver it currently has?
docker run --rm alpine nslookup google.com

# can it resolve the specific local name that's failing?
docker run --rm alpine nslookup mylab.local

# what resolver is it actually configured to use?
docker run --rm alpine cat /etc/resolv.conf

If public names resolve fine but the local one doesn’t, the problem is specifically that the configured resolver doesn’t know your local names — Fix One or Fix Two, rather than a general networking issue. If nothing resolves and even the ping to a public IP fails, the problem is more fundamental (network mode, firewall, or the Docker bridge itself) and DNS specifically isn’t the issue yet.

A related trap: host.docker.internal is a Docker-provided special hostname for reaching the host machine from inside a container, and it’s easy to mistake it for a general DNS fix when actually it’s a single hardcoded mapping for exactly that one address, useful for reaching services on the host itself but irrelevant to resolving arbitrary LAN hostnames.

Another common cause on Linux specifically (host.docker.internal works out of the box on Docker Desktop for Mac and Windows but not by default on Linux): if you’re relying on it, add extra_hosts: ["host.docker.internal:host-gateway"] to the Compose service, since without it the name simply won’t resolve on a Linux Docker host at all.

Is This Worth Understanding, or Just Working Around

Understanding the network-namespace boundary is worth the ten minutes it takes, because it explains a whole category of “works on the host, fails in the container” bugs beyond just DNS — the same namespace isolation is why a container can’t reach a service bound only to the host’s loopback interface either, which is a near-identical symptom with a near-identical fix (bind to 0.0.0.0 or the bridge address, not 127.0.0.1). Once you’ve internalised that a container’s network namespace is genuinely separate from the host’s, rather than a thin wrapper around it, DNS resolution failures like this stop being mysterious and become a short checklist: what resolver is configured, is it reachable, does it know the name. It’s a cheap habit to build once and reuse forever: That’s the same diagnostic habit worth building for DNS-over-HTTPS resolvers at home and for Kubernetes DNS via CoreDNS, where the same underlying question — what resolver, is it reachable, does it actually know this name — keeps coming back in a different container runtime’s clothing.

Smarc
Written by Smarc

Founder and editor of Aside House. A lifelong tinkerer who self-hosts far more than is sensible, hardens Linux boxes for fun, and prods the latest AI tools to see what they can really do. The how-to guides here are the notes Smarc wishes had existed the first time round.

Smarc is the editor of Aside House. The homelab, the hardware and the opinions are real; the guides are drafted with AI assistance. Infrastructure details are genericised on purpose.