Docker pull or container DNS fails with "server misbehaving"
lookup <hostname> on <dns-server-ip>:53: server misbehavingShort answer
'Server misbehaving' is a Go resolver error: the DNS server answered, but with a reply code that is neither success nor name-not-found. Docker is asking a resolver that refuses or fails. First test lookups from the host and from a container, then point the daemon or the container at a DNS server that works.
Fix it fast
1Find out which cause you have
Resolve the same name three ways: on the host, from a throwaway container, and through the daemon with a pull. The one that fails shows which resolver is the problem.
nslookup registry-1.docker.io docker run --rm busybox nslookup registry-1.docker.io docker pull hello-world2Match what you see, then jump to its fix
- 1
The error names an IP address with :53 after 'on'. That is the server which answered badly.The DNS server in use refuses or fails the queryFix - 2
The host looks up names fine, containers on the default bridge do not, and Docker warns about a local DNS resolver in resolv.confThe host resolver is a local forwarder that containers cannot useFix - 3
Only one container or Compose service fails; others on the same host resolve namesA container was started with a DNS address that cannot work from inside itFix
- 1
What does the error look like?
lookup <hostname> on <dns-server-ip>:53: server misbehavingdocker pull fails while a browser on the same machine opens the registry fineA container cannot resolve names that the host resolves
Cause 1 of 3
The DNS server in use refuses or fails the query
1Check
Go's resolver returns this error when the reply code is anything other than success or name-not-found; a server-failure reply is reported as a temporary variant of it. Corporate or router DNS that refuses outside names, or a resolver that is half down, produces exactly this. Ask that same server directly and compare with a public one.
cat /etc/resolv.conf
nslookup registry-1.docker.io 8.8.8.82Fix
If the public server answers and the local one does not, give Docker a DNS server that works, or fix the local resolver. In daemon.json, add a dns key, then restart Docker.
# /etc/docker/daemon.json
{
"dns": ["8.8.8.8", "8.8.4.4"]
}
sudo systemctl restart docker3Verify
The pull that failed now completes.
docker pull hello-worldConfirmed by raw.githubusercontent.com
Cause 2 of 3
The host resolver is a local forwarder that containers cannot use
1Check
Containers on the default bridge get a copy of the host's resolv.conf. On a desktop with dnsmasq, the nameserver in that file is a loopback address, which means nothing inside a container's own network namespace.
cat /etc/resolv.conf
ps aux | grep dnsmasq2Fix
Add a dns key to /etc/docker/daemon.json with real server addresses and restart the daemon. Alternatively turn dnsmasq off in NetworkManager.
# /etc/docker/daemon.json
{ "dns": ["8.8.8.8", "8.8.4.4"] }
sudo systemctl restart docker3Verify
Pull an image, then ping a name from a container.
docker pull hello-world
docker run --rm busybox ping -c 1 example.comConfirmed by docs.docker.com
Cause 3 of 3
A container was started with a DNS address that cannot work from inside it
1Check
DNS requests leave from the container's own network namespace, so --dns=127.0.0.1 points at the container's loopback, not the host. Look at what the container was told to use.
docker inspect --format '{{.HostConfig.Dns}}' my-app
docker exec my-app cat /etc/resolv.conf2Fix
Remove the override, or give a DNS server reachable from the container's network. On a user-defined network, Docker's embedded server at 127.0.0.11 forwards to the host's servers.
docker run --rm --dns 8.8.8.8 busybox nslookup example.com3Verify
The lookup inside the container returns an address.
docker exec my-app nslookup example.comConfirmed by docs.docker.com
How do I stop it coming back?
- Set the dns key in daemon.json on servers whose resolv.conf points at a local forwarder.
- Never pass --dns=127.0.0.1 to a container unless a DNS server runs inside that container.
- After changing network or VPN settings, repeat the three lookups from the first step.
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 container cannot resolve hostnames (pip, apt, curl fail)
[Errno -3] Temporary failure in name resolution
A container copies its DNS settings from the host.
3 causes, each with a fixServers
docker pull cannot reach registry-1.docker.io (no such host or request canceled)
Error response from daemon: Get https://registry-1.docker.io/v2/: net/http: request canceled
These errors mean the Docker daemon, not your shell, could not open a connection to Docker Hub.
2 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 fix