Fix Docker 'Get …: dial tcp: lookup … no such host' errors

What this error means

Docker containers resolve DNS via an embedded resolver (127.0.0.11) that forwards to your host’s DNS. If the host DNS is unreachable, misconfigured, or filtered (VPN, firewall, proxy), you may see errors like:

• Get https://…: dial tcp: lookup <host>: no such host
• dial tcp: lookup <registry> on 127.0.0.11:53: no such host

This guide focuses on Docker environments and shows quick fixes and deeper diagnostics.

Quickstart: fastest fixes

1. Test DNS from a fresh container

# Try resolving a known domain from a throwaway container
docker run --rm alpine:3 sh -c "apk add -q bind-tools >/dev/null && nslookup example.com"

• If this fails, the container’s DNS path is broken.

1. Temporarily override DNS for containers

# Use reliable public DNS as a quick test
docker run --rm --dns 1.1.1.1 --dns 8.8.8.8 alpine:3 sh -c "apk add -q curl >/dev/null && curl -I https://example.com"

• If this works, the issue is your host resolver or Docker’s DNS forwarding.

1. Persist DNS for all containers (Linux)

# /etc/docker/daemon.json
sudo mkdir -p /etc/docker
cat <<'JSON' | sudo tee /etc/docker/daemon.json
{
  "dns": ["1.1.1.1", "8.8.8.8"]
}
JSON

sudo systemctl restart docker

• Replace with your corporate DNS if needed.

Minimal working example (reproduce and fix)

Reproduce the failure by forcing a bad DNS server, then fix it by providing a good one.

# Reproduce: force an unroutable DNS (will fail with "no such host")
docker run --rm --dns 203.0.113.1 alpine:3 sh -c "apk add -q curl bind-tools >/dev/null && nslookup example.com && curl -sS https://example.com"

# Fix: use a working DNS server (should resolve and fetch headers)
docker run --rm --dns 1.1.1.1 alpine:3 sh -c "apk add -q curl bind-tools >/dev/null && nslookup example.com && curl -I https://example.com"

Step-by-step diagnosis

1. Confirm the host resolves domains

# Linux
getent hosts example.com || true
cat /etc/resolv.conf

# macOS
scutil --dns | sed -n '1,120p'

# Windows (PowerShell)
Resolve-DnsName example.com

• If the host cannot resolve, fix the OS/VPN/proxy DNS first.

1. Check container DNS configuration

# Start a shell and inspect resolver inside container
docker run -it --rm alpine:3 sh -c "cat /etc/resolv.conf; echo; nslookup example.com || true"

• By default you should see nameserver 127.0.0.11 inside containers.
• If resolution fails, host upstream DNS may be wrong or unreachable.

1. Identify host DNS upstreams

• Linux with systemd-resolved often uses 127.0.0.53 as a stub. Real upstreams are visible via:

resolvectl status | sed -n '1,200p'

• If upstreams look wrong or are VPN-only, prefer setting them explicitly in Docker.

1. Try alternative networks

# Verify container can reach UDP/TCP 53 externally (from host)
nc -zu 1.1.1.1 53 || true

# Try a fresh user-defined bridge
docker network create testnet
docker run --rm --network testnet alpine:3 sh -c "apk add -q bind-tools >/dev/null && nslookup example.com"

1. Persist a DNS policy

• Global (daemon-level): set /etc/docker/daemon.json "dns": ["<dns1>", "<dns2>"] and restart Docker.
• Per container: docker run --dns <ip> --dns-search <domain> …
• Docker Compose:

version: "3.8"
services:
  app:
    image: alpine:3
    command: ["sh", "-c", "apk add -q curl && curl -I https://example.com"]
    dns:
      - 1.1.1.1
      - 8.8.8.8
    dns_search:
      - corp.example

1. Registries and proxies

• If the error occurs during docker pull, check proxy variables on the host:
  • HTTP_PROXY, HTTPS_PROXY, NO_PROXY (and lowercase variants)
  • Ensure registry domains are included in NO_PROXY for internal networks.

Common causes and targeted fixes

• systemd-resolved stub resolver on Linux

  • Symptom: container uses 127.0.0.11 → host 127.0.0.53 → upstream fails.
  • Fix: set explicit upstreams in /etc/docker/daemon.json or point /etc/resolv.conf to real DNS (not the stub), then restart Docker.

• VPN or split-horizon DNS

  • Symptom: corporate domains fail inside containers.
  • Fix: use the VPN’s DNS servers in Docker config; add dns_search for internal suffixes.

• Firewall blocking DNS

  • Symptom: nslookup times out; UDP 53 blocked.
  • Fix: allow outbound UDP/TCP 53 to your resolvers. Test with nc -zu <dns> 53.

• WSL2 / Docker Desktop routing

  • Symptom: Windows host resolves, container fails.
  • Fix: in Docker Desktop, enable “Use host DNS” or set explicit DNS in Docker Engine settings.

• Mis-set proxy

  • Symptom: curl http(s) works to proxy, DNS lookup fails for non-proxied hosts.
  • Fix: correct NO_PROXY and ensure the proxy isn’t intercepting DNS.

Verification checklist

• Host resolves external and internal domains.
• Container nslookup example.com succeeds.
• docker pull works for public and private registries.
• No frequent timeouts in logs; resolv.conf in containers lists 127.0.0.11 or your configured DNS.

Performance notes

• Fallback latency: listing many DNS servers can slow first-byte timing when the first is unreachable. Keep 1–2 reliable servers.
• ndots/search: large search domains and high ndots cause extra queries. If you control images, set minimal search lists to reduce lookups.
• Caching: Docker’s embedded DNS does basic forwarding, not full caching. For heavy workloads, point Docker to a fast local caching resolver (e.g., on the host) to reduce latency.
• Avoid per-container --dns unless necessary; prefer daemon-level config to reduce drift and startup variance.

Pitfalls

• Editing /etc/resolv.conf inside a running container is ephemeral and resets on restart.
• Hardcoding public DNS may break access to internal zones and registries; include corporate DNS when needed.
• Some environments block UDP 53; ensure TCP 53 works or use resolvers that support TCP fallback.
• Compose overrides: service-level dns can mask daemon-level settings—check both.

Tiny FAQ

• Why does docker pull fail with this error?

  • The Docker engine itself relies on host DNS. If it can’t resolve registry domains, pulls fail. Fix host/Docker daemon DNS.

• Is 127.0.0.11 required in containers?

  • It’s Docker’s embedded DNS proxy. You can override with real DNS servers, but the default is convenient and supports service discovery on user-defined networks.

• Should I use 8.8.8.8 everywhere?

  • Use what’s allowed and fastest in your network. In corporate/VPN setups, internal DNS is required for private zones.

• How do I test quickly without changing global config?

  • Use docker run --dns … on a test container, then apply a persistent fix in daemon.json or Compose.

• Do I need to restart Docker after daemon.json changes?

  • Yes. systemctl restart docker (Linux) or apply via Docker Desktop’s settings (macOS/Windows).