Maaz Zindani

Loading the index…

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

Docker pull or container DNS fails with "server misbehaving"

Errorlookup <hostname> on <dns-server-ip>:53: server misbehaving

Short 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.

  • Applies to Docker Engine 28 and 29, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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-world
  2. 2Match what you see, then jump to its fix

    1. 1The 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. 2The 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. 3Only 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

What does the error look like?

  • lookup <hostname> on <dns-server-ip>:53: server misbehaving
  • docker pull fails while a browser on the same machine opens the registry fine
  • A 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.8

2Fix

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 docker

3Verify

The pull that failed now completes.

docker pull hello-world

Confirmed by raw.githubusercontent.com

Did this fix it?

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 dnsmasq

2Fix

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 docker

3Verify

Pull an image, then ping a name from a container.

docker pull hello-world
docker run --rm busybox ping -c 1 example.com

Confirmed by docs.docker.com

Did this fix it?

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.conf

2Fix

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.com

3Verify

The lookup inside the container returns an address.

docker exec my-app nslookup example.com

Confirmed by docs.docker.com

Did this fix it?

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

Next step

Want this handled for good?

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