Docker Engine / Troubleshooting
Docker Container DNS Not Working: Separate IP Path from Name Resolution
Confirm the IP path first, then separate default-bridge and user-defined-bridge resolver behavior when a container reaches external IPs but hostname resolution fails.
A failing hostname with working external IPs is a DNS-layer observation, not a general connectivity failure. Confirm the IP path first; only then does resolver diagnosis begin.[1]
Resolver behavior depends on the bridge type. Containers that attach to the default bridge network receive a copy of the host resolver file, while containers that attach to a custom network use the embedded DNS server, which forwards external lookups to the DNS servers configured on the host. The two cases must never be diagnosed with the same expectations.[1][2]
Custom DNS settings change this picture further. Per-container DNS flags and daemon-level DNS settings, documented under the daemon DNS options, alter which resolvers answer, so establish whether custom DNS is configured and where before blaming any resolver component.[1][6]
Sections
Applicability
- Products
- Docker Engine
- Scope
- For rootful Docker Engine on Linux with bridge networking, where a running container reaches external destinations by IP but hostname resolution fails. The container may use the default bridge or a user-defined bridge network, and those two cases follow different resolver behavior. This page does not cover general connectivity failure with failing IPs, published-port inbound access, host or none network mode, macvlan, ipvlan, overlay or Swarm, rootless Engine, or Docker Desktop, WSL, and macOS networking.[1][2][7]
- Last verified
Symptoms
- The container reaches an external destination by IP address, but the same or comparable destinations fail by hostname. The IP evidence must be recorded; an untested IP path does not establish a DNS-only failure.[1]
- The failure may affect every hostname or only specific names. A single failing name with working general resolution makes a total resolver outage less likely and the investigation name, query, and path specific, without proving the resolver healthy or assigning a unique root cause.[1]
Quick diagnosis
Confirm the IP path first. Failing hostnames with working IPs isolate the DNS layer.
Confirm the IP path before DNS work
Test an external destination by IP from the container context and record the result. If external IPs also fail, stop and use the container connectivity diagnosis instead; this page requires IP-path evidence.[1]
Record default bridge versus user-defined network
Record whether the container uses the default bridge network or a user-defined bridge network. Resolver expectations differ between the two: user-defined bridge networks provide automatic Docker DNS resolution of container names and aliases, which the default bridge does not provide in the same way.[1][2][4]
docker network inspect <network>Record the resolver configuration in effect
Record the resolver configuration the container actually uses and whether custom DNS is configured at container or daemon level. An assumed resolver is not an observed one.[1][5]
docker inspect <container>Interactive troubleshooter
Your answers stay in this browser tab. The tool does not connect to your systems or send diagnostic results.
Guided check / step 1
Is the IP path confirmed working?
DNS-only diagnosis requires recorded external-IP success. Without it, the symptom is unclassified.[1]
Read the complete diagnostic tree without using the controls
- Is the IP path confirmed working?
DNS-only diagnosis requires recorded external-IP success. Without it, the symptom is unclassified.[1]
- Yes, external IPs work, names fail → Which network mode does the container use?
- No, IPs fail or were never tested → Confirm the IP path first
- I have not established this → Test an external destination by IP
- Test an external destination by IP
Test an external destination by IP from the container context and record the result before any resolver conclusion.[1]
- What did the IP test show?
Only confirmed IP success with failing names continues on this page.[1]
- External IPs work, names fail → Which network mode does the container use?
- External IPs fail or were never tested → Confirm the IP path first
- Confirm the IP path first
Without recorded external-IP success, continue with the container connectivity diagnosis, which separates attachment, addressing, gateway, and external path layers. Resolver work built on an untested IP path misdirects the repair.[1]
- Which network mode does the container use?
Establish the network mode before any bridge resolver expectations. Non-bridge modes follow different models.[1][7]
- Bridge (default or user-defined) → Default bridge or user-defined bridge?
- Host, none, or another driver → Non-bridge modes need their own diagnosis
- I have not checked → Record the container network mode
- Record the container network mode
Record the network mode from Docker-side inspection before any resolver step.[5][7]
- What did the mode check show?
Only bridge attachments continue on this page.[1]
- Bridge (default or user-defined) → Default bridge or user-defined bridge?
- Host, none, or another driver → Non-bridge modes need their own diagnosis
- Non-bridge modes need their own diagnosis
Host, none, macvlan, ipvlan, overlay, rootless, and Docker Desktop networking do not share bridge resolver behavior. Record the mode and use the matching diagnosis; never apply bridge resolver expectations and never change the network mode as a test.[1][7]
- Default bridge or user-defined bridge?
Default-bridge containers receive a copy of the host resolver file; user-defined-network containers use the embedded DNS server. The default bridge does not provide the same automatic container-name DNS behavior as user-defined bridges.[1][2]
- Default bridge network → Is custom DNS configured?
- User-defined bridge network → Is custom DNS configured?
- I have not checked → Record which bridge the container uses
- Record which bridge the container uses
Record the container network attachment and whether it is the default bridge or a user-defined network.[4][2]
- What did the bridge check show?
Resolver expectations follow the bridge type actually in use.[2]
- Default bridge network → Is custom DNS configured?
- User-defined bridge network → Is custom DNS configured?
- Is custom DNS configured?
Establish whether custom DNS is configured at container or daemon level before blaming any resolver component.[1]
- Yes, custom DNS is configured → Investigate the custom resolver, not the default path
- No custom DNS → Do all hostnames fail or only specific names?
- I have not checked → Inspect the resolver configuration in effect
- Inspect the resolver configuration in effect
Record the resolver configuration the container actually uses and any custom DNS at container or daemon level.[1][5]
- What did the resolver inspection show?
A custom resolver shifts the investigation to its own reachability and behavior.[1]
- Custom DNS is configured → Investigate the custom resolver, not the default path
- No custom DNS → Do all hostnames fail or only specific names?
- Investigate the custom resolver, not the default path
With custom DNS configured, failures reflect that resolver reachability and behavior. Record where it is configured, test its reachability, and do not replace it with public servers as a generic fix.[1]
- Do all hostnames fail or only specific names?
General failure continues at resolver and upstream layers; a single failing name narrows to that name, its zone, or its upstream.[1]
- Every hostname fails → Separate the resolver in effect from its upstreams
- Only specific names fail → Narrow to the failing name, not the resolver
- I have not tested this → Compare several unrelated hostnames
- Compare several unrelated hostnames
Test several unrelated hostnames and record which fail and which succeed.[1]
- What did the hostname comparison show?
A single failing name makes a total resolver outage less likely but does not prove the resolver healthy.[1]
- Every hostname fails → Separate the resolver in effect from its upstreams
- Only specific names fail → Narrow to the failing name, not the resolver
- Separate the resolver in effect from its upstreams
With a confirmed IP path, classified bridge type, and no custom DNS, general resolution failure narrows to the resolver in effect or its upstream servers. Test each layer explicitly; a failing lookup alone never identifies which one. Hand the classified evidence to the deployment or network owner.[1][2]
- Narrow to the failing name, not the resolver
Working general resolution with one failing name makes a total resolver outage less likely and the investigation name, query, and path specific; it does not prove the resolver healthy. Record exactly which names fail and which succeed and investigate the name side.[1]
Detailed diagnosis
1. Require IP-path evidence
Require a recorded external-IP success before DNS diagnosis. Without it, the symptom is unclassified, not DNS-only.[1]
2. Establish the network mode
Establish which network mode the container uses. Host, none, macvlan, ipvlan, overlay, rootless, and Docker Desktop networking follow different models and must never follow bridge resolver expectations.[1][7]
docker inspect <container>3. Separate default bridge from user-defined bridge
Determine whether the container uses the default bridge or a user-defined bridge network. Default-bridge containers receive a copy of the host resolver file; user-defined-network containers use the embedded DNS server that forwards to host-configured servers. The default bridge does not provide the same automatic container-name DNS behavior as user-defined bridges.[1][2]
docker network inspect <network>4. Inspect custom DNS before blaming a resolver
Inspect whether custom DNS is configured for the container or daemon before attributing the failure to any resolver component. A custom resolver shifts the investigation to its own reachability and behavior.[1]
5. Separate general failure from name-specific failure
Test whether every hostname fails or only specific names. General failure continues at resolver and upstream layers; a single failing name narrows to that name, its zone, or its upstream.[1]
Supported scenarios
These observations narrow the next investigation; they do not establish a unique cause.
IP connectivity was never confirmed
Without recorded external-IP success, the symptom is unclassified connectivity failure, not a DNS-only problem. DNS diagnosis built on an untested IP path misdirects the repair.[1]
How to check: Test an external destination by IP and record the result before any resolver conclusion.[1]
Default-bridge expectations applied to the wrong network
Container-name resolution between containers exists on user-defined bridge networks, not on the default bridge. Expecting name resolution on the default bridge misclassifies normal behavior as failure.[2][1]
How to check: Record which bridge type the container uses before judging any name-resolution observation.[2][4]
A custom resolver answers instead of the default path
Per-container DNS flags or daemon-level DNS settings, documented under the daemon DNS options, replace the default resolver path. Failures then reflect the custom resolver reachability and behavior, not necessarily the Docker-provided path.[1][6]
How to check: Establish whether custom DNS is configured and where before blaming the default resolver behavior.[1][5]
General resolution fails at resolver or upstream layers
Every hostname failing with a confirmed IP path and classified resolver configuration narrows the fault to the resolver in effect or its upstream servers. A failing lookup alone never identifies which of the two.[1]
How to check: Separate the resolver in effect from its upstream servers and test each layer explicitly.[1]
Only specific names fail
Working general resolution with one failing name makes a total resolver outage less likely and the investigation name, query, and path specific. This does not prove the resolver healthy and does not assign a unique root cause from this observation alone.[1]
How to check: Test several unrelated hostnames and record which names fail and which succeed.[1]
The actual failure is inbound published-port access
A service unreachable from another LAN device is an inbound published-port observation even when local name resolution also looks suspicious. Direction must be established before resolver work.[3]
How to check: Record the direction of the failing request before resolver diagnosis.[3]
Next actions and procedure boundaries
Hand off a resolver finding with evidence
If evidence narrows the fault to the resolver in effect or its upstream servers, record the bridge type, the resolver configuration in effect, the custom DNS state, and which names fail versus succeed, and provide those observations to the deployment or network owner. This page supplies no resolver-change command.[1][2]
Before any separately authorized DNS change
Before changing anything
- Risk
- A DNS configuration change can break local, VPN, and split-DNS name resolution for workloads beyond the one being diagnosed.[1]
- Safer check
- Confirm the bridge type, the resolver in effect, the custom DNS state, and the general-versus-name-specific scope before considering a change.[1][2]
- Expected result
- A scoped plan should state which names should start resolving and which existing names must keep resolving; verify both after any separate change.[1]
- Backup / recovery access
- HomeLabFix requires saved container, daemon, and host resolver settings and independent host management access before disruptive work.[1][6]
- Rollback
- There is no universal rollback recipe here. The owner must verify restoration of the prior resolver configuration for this installation; if recovery is not established, stop.[1]
Planning boundary only: changing container, daemon, or host DNS configuration can alter split-DNS, local zones, VPN names, and corporate or homelab resolution behavior. Replacing resolvers with public servers is not a generic fix. The responsible deployment and network owner must approve the exact change; this page supplies no mutation command.[1]
Escalate a design mismatch with evidence
When observations show the container network design does not match the site design, keep the container configuration intact, record mode, bridge type, resolver state, and failure scope, and escalate to the network owner. Do not convert one network mode or driver into another as a probe.[1][2]
Warnings and boundaries
Sources
Links were reviewed on 2026-09-11. Reachability and automated validation do not replace editorial verification of each claim.
- Networking overview
Docker · Tier A · accessed 2026-09-11 - Bridge network driver
Docker · Tier A · accessed 2026-09-11 - Port publishing and mapping
Docker · Tier A · accessed 2026-09-05 - docker network inspect
Docker · Tier A · accessed 2026-09-11 - docker inspect
Docker · Tier A · accessed 2026-09-11 - dockerd
Docker · Tier A · accessed 2026-09-11 - Host network driver
Docker · Tier A · accessed 2026-09-05