Docker container cannot resolve hostnames (pip, apt, curl fail)
Temporary failure in name resolutionShort 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.
Fix it fast
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.com2Match what you see, then jump to its fix
- 1
The 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
Only 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
Even the ping to the IP address failsDocker's firewall rules were turned off, so containers have no route outFix
- 1
What does the error look like?
Temporary failure in name resolution[Errno -3] Temporary failure in name resolutionWARNING: 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 dnsmasq2Fix
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 restart3Verify
A container resolves a public name.
docker run --rm alpine ping -c2 example.comConfirmed by docs.docker.com
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-container2Fix
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.com3Verify
The name resolves inside that container.
docker run --rm --dns 1.1.1.1 alpine nslookup example.comConfirmed by docs.docker.com
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.json2Fix
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 docker3Verify
The IP ping from a container now works.
docker run --rm alpine ping -c2 1.1.1.1Confirmed by docs.docker.com
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 fixServers
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fixServers
sam local fails: Running AWS SAM projects locally requires Docker
Cannot connect to the Docker daemon. Is the docker daemon running on this host?
sam local start-api and sam local invoke run your function inside a Docker container, so SAM stops if it cannot talk to Docker.
3 causes, each with a fixServers
dnf fails to download repo metadata in a CentOS 8 Docker build
The same Dockerfile built fine before 2022
CentOS Linux 8 reached end of life on 31 December 2021 and its content left the mirrors.
2 causes, each with a fixServers
Let's Encrypt cannot find the _acme-challenge TXT record for your domain
The TXT record added at the DNS host never shows up for validation
With the DNS-01 challenge, Let's Encrypt looks up a TXT record named _acme-challenge under your domain.
3 causes, each with a fixServers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fix