Introduction

When a Docker container cannot resolve DNS names on a private network, the problem is usually not "Docker DNS is broken" in the abstract. It is usually one of three concrete issues: the container is using the wrong DNS server, the DNS server is unreachable from the container network, or the private name only resolves from a specific VPN or host interface. The fix starts by separating name resolution from plain IP connectivity.

Check Whether It Is DNS or Routing

Before changing Docker settings, test whether the container can reach the target network at all.

docker exec -it mycontainer sh
ping 10.0.0.10
nslookup internal.example.local

If IP connectivity fails, this is a routing or firewall problem, not a DNS problem. If IP connectivity works but hostname resolution fails, then DNS configuration is the right place to focus.

Understand Docker's DNS Behavior

Containers do not magically inherit every host networking detail. Depending on how Docker is configured, a container may use:

• the host resolver configuration
• Docker's embedded DNS on user-defined networks
• explicit --dns entries
• daemon-level DNS settings

A common first inspection step is:

docker exec -it mycontainer cat /etc/resolv.conf

If the nameserver shown there cannot answer queries for your private domain, resolution will fail even though the host machine itself resolves the name.

Set the DNS Server Explicitly

If the private network has an internal DNS server, point the container to it directly.

1docker run --rm \
2  --dns 10.0.0.53 \
3  alpine:3.20 \
4  nslookup internal.example.local

In Compose:

1services:
2  app:
3    image: alpine:3.20
4    dns:
5      - 10.0.0.53

This is often the cleanest fix when the host can resolve names only because a VPN client injected special resolvers that Docker did not propagate correctly.

Be Careful with VPN and Split DNS

Private-network DNS issues often appear only when a VPN is connected. The host may be using split DNS rules that send certain domains to corporate resolvers, but the container only sees a simplified resolv.conf.

That creates a pattern like this:

• host resolves internal.example.local
• container cannot resolve the same name
• public names still work

In that case, explicitly setting the internal DNS server usually works better than assuming Docker will mirror the host's resolver behavior perfectly.

User-Defined Networks and Container-to-Container DNS

Docker also provides embedded DNS for service discovery on user-defined bridge networks. That only solves container name resolution inside Docker, not resolution of arbitrary private corporate domains.

Example:

1docker network create app-net
2
3docker run -d --name db --network app-net postgres:16
4docker run --rm --network app-net alpine:3.20 nslookup db

This lets one container resolve another by container name. It does not automatically make internal.example.local resolve unless the upstream nameserver knows that record.

Daemon-Wide DNS Configuration

If many containers need the same private DNS behavior, configure the Docker daemon instead of repeating --dns everywhere.

Example daemon config:

{
  "dns": ["10.0.0.53", "10.0.0.54"]
}

On Linux, this is typically stored in /etc/docker/daemon.json. After changing it, restart Docker.

Use daemon-wide settings only if the DNS requirement is broadly correct for the host. Otherwise, per-container or per-project settings are safer.

Troubleshooting Sequence

A reliable order is:

1. test IP reachability from inside the container
2. inspect /etc/resolv.conf
3. query the intended DNS server directly with nslookup
4. try explicit --dns
5. inspect VPN, firewall, or host routing behavior if private resolvers are unreachable

Randomly changing network drivers before doing those checks usually wastes time.

Common Pitfalls

• Assuming a successful host lookup means containers inherit identical DNS behavior.
• Treating a routing problem as a DNS problem.
• Forgetting that Docker's embedded DNS only helps with Docker-managed names.
• Using public DNS servers for private domains that only exist internally.
• Ignoring VPN split-DNS behavior when resolution works on the host but not in the container.

Summary

• Separate DNS failure from plain network reachability first.
• Inspect the container's resolv.conf instead of assuming it matches the host.
• Use --dns or Compose dns when private resolvers must be explicit.
• Docker service discovery and private-network corporate DNS are different concerns.
• VPN and split-DNS setups are a very common cause of container-only resolution failures.