How to fix 'temporary failure in name resolution' inside containers

Overview

A container showing “Temporary failure in name resolution” cannot resolve DNS names. Common causes:

• Host DNS misconfiguration (VPN, corporate DNS, systemd-resolved).
• Docker’s embedded DNS (127.0.0.11) not reaching upstream resolvers.
• Broken /etc/resolv.conf inside the container or on the host.
• Firewall or network policies blocking UDP/TCP 53.

This guide focuses on Docker (Linux, Docker Desktop) and gives fast, practical remedies.

Quickstart (fast path)

1. Test DNS inside a fresh container:

• If this fails, proceed to diagnosis.

# Expect a line with an IP if DNS works
docker run --rm alpine:3.20 getent hosts example.com

1. Try a known-good resolver temporarily:

docker run --rm --dns 1.1.1.1 alpine:3.20 getent hosts example.com

• Works: configure DNS per-container or at the daemon level (see below).
• Fails: check host DNS, firewall, or upstream reachability.

1. For docker-compose services, set dns:

auth-service:
  image: alpine:3.20
  command: ["sh", "-c", "getent hosts example.com && sleep 3600"]
  dns:
    - 1.1.1.1
    - 9.9.9.9

1. To set daemon-wide DNS (all containers):

{
  "dns": ["1.1.1.1", "9.9.9.9"],
  "dns-search": []
}

# Save as /etc/docker/daemon.json (Linux) then restart
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json >/dev/null <<'JSON'
{
  "dns": ["1.1.1.1", "9.9.9.9"],
  "dns-search": []
}
JSON
sudo systemctl restart docker

Minimal working example

The following reproduces the error on purpose, then fixes it.

# Reproduce: use an invalid resolver
docker run --rm --dns 0.0.0.0 alpine:3.20 getent hosts example.com || echo "DNS failed"

# Fix: use a reachable resolver
docker run --rm --dns 1.1.1.1 alpine:3.20 getent hosts example.com

If the second command resolves to an IP, your container networking is fine and the issue is DNS configuration.

Diagnose methodically

1. Inspect resolv.conf inside the container:

docker run --rm alpine:3.20 cat /etc/resolv.conf

• Docker’s embedded DNS usually appears as nameserver 127.0.0.11.
• Large search domains can slow or break lookups.

1. Try multiple tools (avoid relying only on ping):

# Install tools in a disposable shell
docker run -it --rm alpine:3.20 sh -lc 'apk add --no-cache bind-tools > /dev/null; nslookup example.com; dig +short example.com'

1. Verify host DNS works:

getent hosts example.com || nslookup example.com || dig +short example.com

If host cannot resolve, containers won’t either—fix host DNS first (VPN, network manager, systemd-resolved).

1. Check connectivity to DNS servers:

# Replace with your intended DNS server
DNS=1.1.1.1
# UDP may be filtered; test TCP too
nc -vz -w 3 $DNS 53 || echo "TCP 53 blocked"

1. Examine Docker networks:

docker network ls
docker network inspect bridge | grep -E 'Subnet|Gateway'

Fix options (choose one that matches your environment)

A. Per-container DNS (simple, explicit)

• Docker CLI:

docker run --rm --dns 1.1.1.1 --dns 9.9.9.9 alpine:3.20 getent hosts example.com

• docker-compose:

services:
  app:
    image: alpine:3.20
    dns:
      - 1.1.1.1
      - 9.9.9.9
    dns_opt:
      - timeout:1
      - attempts:2

Use internal corporate DNS when on VPN; public resolvers may not see internal zones.

B. Daemon-wide DNS (centralized)

Set once in /etc/docker/daemon.json and restart Docker:

{
  "dns": ["10.0.0.53", "1.1.1.1"],
  "dns-search": ["corp.local"]
}

This ensures all containers use these resolvers instead of relying on host stub resolvers like 127.0.0.53.

C. systemd-resolved specifics (Linux)

If your host uses systemd-resolved, /etc/resolv.conf may be a stub pointing to 127.0.0.53. Docker’s embedded DNS may not reach the real upstreams. Choose one:

• Configure daemon.json "dns" with the real upstreams (recommended).
• Or point Docker to the resolved-generated file by extracting the upstreams, then set them in daemon.json.
• Avoid bind-mounting the host’s /etc/resolv.conf into containers unless you know the implications.

D. Reset Docker networking

• Remove unused networks and restart Docker:

docker network prune -f
sudo systemctl restart docker

• If a custom bridge was misconfigured, recreate it with a clean subnet not overlapping your VPN.

E. Firewall and policy checks

• Ensure outbound UDP/TCP 53 to your DNS servers is allowed from the Docker bridge subnet.
• Some environments require DNS over TCP; ensure your resolver supports it.

Common pitfalls

• Hard-coding public DNS on corporate networks can break internal name resolution.
• Ping is not a DNS tool; a host can resolve but still drop ICMP echo.
• Large or incorrect search domains cause slow lookups and timeouts.
• Stale cached images aren’t relevant; this is runtime network config, not build-time.
• IPv6-only or DNS64/NAT64 networks need IPv6-capable resolvers.

Performance notes

• Reduce lookup latency with DNS options:

# Example to try inside the container context
options timeout:1 attempts:2 rotate

• In docker run:

docker run --rm \
  --dns 1.1.1.1 --dns 9.9.9.9 \
  --dns-opt timeout:1 --dns-opt attempts:2 --dns-opt rotate \
  alpine:3.20 getent hosts example.com

• In compose:

services:
  app:
    image: alpine:3.20
    dns: ["1.1.1.1", "9.9.9.9"]
    dns_opt: ["timeout:1", "attempts:2", "rotate"]

• Avoid long search lists; prefer explicit FQDNs.
• If many containers resolve the same domains repeatedly, add a local caching resolver on the host or network.

Step-by-step checklist

1. Confirm host DNS works (getent/nslookup/dig).
2. Test a clean container with getent hosts example.com.
3. If failing, retry with --dns 1.1.1.1 to distinguish DNS vs network.
4. If --dns works, set dns in compose or daemon.json and restart Docker.
5. On VPN/corp networks, switch to internal DNS servers.
6. If still failing, inspect firewall rules for outbound 53 and Docker bridge subnets.
7. Tweak dns_opt to reduce timeouts; review search domains.

Tiny FAQ

• Q: Why does /etc/resolv.conf show 127.0.0.11 in containers? A: That’s Docker’s embedded DNS proxy. It forwards to upstream resolvers from the host or daemon config.

• Q: Should I mount the host resolv.conf into containers? A: Usually no. Prefer Docker’s dns and dns_search settings; host stubs (127.0.0.53) can break in containers.

• Q: My host resolves fine but containers don’t. Why? A: The host may use a stub resolver or split DNS over VPN. Configure container DNS with the real upstreams.

• Q: Is using public DNS safe at work? A: It may break internal names and violate policy. Use corporate DNS on corporate networks.

• Q: Can this be a build-time issue (docker build)? A: Yes; use --network during builds or set daemon DNS so build stages can resolve names consistently.