Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Docker container cannot resolve hostnames (pip, apt, curl fail)

ErrorTemporary failure in name resolution

Short answer

A container copies its DNS settings from the host. If the host resolver is a loopback address, the container cannot reach it, so lookups fail while the host itself works. Test with a public IP first, then set explicit DNS servers in daemon.json or per container.

  • Applies to Docker Engine 27, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Separate a DNS problem from a network problem: ping an IP address, then a name, from a throwaway container.

    docker run --rm alpine ping -c2 1.1.1.1
    docker run --rm alpine ping -c2 example.com
  2. 2Match what you see, then jump to its fix

    1. 1The IP ping works, the name ping fails; the Docker log shows the local-resolver warningThe host resolver is a loopback address the container cannot useFix
    2. 2Only a single container or one compose service fails, for example one that needs an internal DNS serverOne container needs a different DNS server than the daemon defaultFix
    3. 3Even the ping to the IP address failsDocker's firewall rules were turned off, so containers have no route outFix

What does the error look like?

  • Temporary failure in name resolution
  • [Errno -3] Temporary failure in name resolution
  • WARNING: Local (127.0.0.1) DNS resolver found in resolv.conf and containers can't use it.

Cause 1 of 3

The host resolver is a loopback address the container cannot use

1Check

Containers get a copy of the host /etc/resolv.conf. A container has its own network namespace, so 127.0.0.1 there is the container, not the host. The Docker docs name dnsmasq as the usual case.

cat /etc/resolv.conf
ps aux | grep dnsmasq

2Fix

Give the daemon real DNS servers in /etc/docker/daemon.json (add at least one that resolves public names), then restart Docker.

{
  "dns": ["8.8.8.8", "8.8.4.4"]
}

sudo service docker restart

3Verify

A container resolves a public name.

docker run --rm alpine ping -c2 example.com

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

One container needs a different DNS server than the daemon default

1Check

The --dns flag is applied per container on docker run or docker create. A value of 127.0.0.1 there points at the container's own loopback.

docker inspect --format '{{.HostConfig.Dns}}' my-container

2Fix

Pass the DNS server for that container; repeat the flag to give several.

docker run --rm --dns 1.1.1.1 alpine ping -c2 example.com

3Verify

The name resolves inside that container.

docker run --rm --dns 1.1.1.1 alpine nslookup example.com

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

Docker's firewall rules were turned off, so containers have no route out

1Check

The Docker docs say that if iptables handling is disabled without replacement rules, bridge containers cannot reach internet hosts through masquerading, and that disabling it is likely to break container networking.

cat /etc/docker/daemon.json

2Fix

Remove "iptables": false (and "ip6tables": false) from daemon.json, or add your own masquerade rules, then restart Docker.

sudo nano /etc/docker/daemon.json
sudo systemctl restart docker

3Verify

The IP ping from a container now works.

docker run --rm alpine ping -c2 1.1.1.1

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Set dns in daemon.json on servers whose host resolver is a local cache.
  • Keep a throwaway 'ping IP then ping name' test in your runbook.
  • Do not disable Docker's iptables management unless you write the replacement rules.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Servers

Docker pull or container DNS fails with "server misbehaving"

docker pull fails while a browser on the same machine opens the registry fine

'Server misbehaving' is a Go resolver error: the DNS server answered, but with a reply code that is neither success nor name-not-found.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.