🚨 Docker Error Guide: 'lookup <registry> on 127.0.0.11:53: no such host' — Fix Docker DNS

Overview

This error appears when Docker tries to reach a registry to pull an image but cannot resolve the registry’s hostname to an IP address. The 127.0.0.11:53 in the message is the giveaway — that is Docker’s own embedded DNS resolver, not your system resolver:

Error response from daemon: Get "https://registry.example.com/v2/": dial tcp: lookup registry.example.com on 127.0.0.11:53: no such host

no such host specifically means the DNS query returned NXDOMAIN — the name does not exist as far as the resolver could determine. This is distinct from temporary failure in name resolution, which means the resolver itself was unreachable or timed out. Here the lookup completed and came back empty: either the hostname is wrong, or the DNS server Docker forwarded the query to genuinely has no record for it.

Symptoms

• docker pull, docker run, or docker build fails immediately with the message above.
• The failing hostname is a registry — Docker Hub (registry-1.docker.io), a cloud registry (*.dkr.ecr.*.amazonaws.com, gcr.io, ghcr.io), or a private/corporate registry.
• Other hosts on the machine resolve fine (nslookup from the shell works) but Docker still fails.
• The 127.0.0.11:53 resolver address appears — confirming the lookup is going through Docker’s embedded DNS, which forwards to the daemon’s configured upstreams.
• Works on one host or network and fails on another (home vs. VPN vs. corporate LAN).

Common Root Causes

• A typo or wrong hostname in the image reference — registy.example.com, a missing subdomain, or a stale registry domain. NXDOMAIN is exactly what a typo produces.
• The daemon’s upstream DNS cannot resolve the name — the host’s /etc/resolv.conf (which Docker inherits by default) points at a resolver that lacks the record, common with internal/split-horizon corporate DNS.
• Missing dns configuration in /etc/docker/daemon.json when the host relies on a DNS server that containers/daemon can’t reach (e.g. 127.0.0.53 systemd-resolved stub inside the daemon’s namespace).
• A private registry that only exists on a VPN or internal zone while the resolver in use is a public one (8.8.8.8) that will never have the record.
• Split-horizon DNS — the internal name resolves on-LAN but the configured upstream is the external view where it does not exist.

Diagnostic Workflow

First separate a typo from a real DNS problem. Try to resolve the exact hostname from the failing message using the same DNS the host uses:

getent hosts registry.example.com
nslookup registry.example.com
dig +short registry.example.com

If these also return nothing, the name genuinely does not resolve — check for a typo or that you are on the right network/VPN. If the shell resolves it but Docker does not, the daemon is using a different resolver. Inspect what the daemon inherits:

cat /etc/resolv.conf
docker info | grep -i 'registry\|proxy'
journalctl -u docker --since '10 min ago' | grep -i 'dns\|lookup\|no such host'

Test resolution from inside Docker’s networking, which uses the embedded 127.0.0.11 resolver:

docker run --rm alpine nslookup registry.example.com
docker run --rm alpine cat /etc/resolv.conf

To point the Docker daemon at explicit upstream DNS servers, configure /etc/docker/daemon.json:

{
  "dns": ["10.0.0.2", "1.1.1.1"]
}

Then restart the daemon and confirm it picked up the change:

sudo systemctl restart docker
docker run --rm alpine nslookup registry.example.com

For a single container you can override without touching the daemon:

docker run --dns 10.0.0.2 --rm alpine nslookup registry.example.com

Example Root Cause Analysis

A developer could pull from Docker Hub at the office but every pull from the company’s internal registry nexus.corp.internal failed with no such host when working from home over the VPN.

getent hosts nexus.corp.internal on the host returned an address — so the OS resolved it. But docker run --rm alpine nslookup nexus.corp.internal returned NXDOMAIN. The difference: the host’s /etc/resolv.conf listed 127.0.0.53, the systemd-resolved stub, which had learned the corporate zone from the VPN link. Docker’s embedded resolver forwards to the daemon’s upstreams, and the daemon had been configured with a static "dns": ["8.8.8.8"] in daemon.json from an old troubleshooting session. Google’s public DNS has no record for nexus.corp.internal, so every internal pull came back NXDOMAIN.

The fix was to set the daemon’s upstream to the corporate resolver that actually serves the internal zone:

{
  "dns": ["10.20.0.10", "10.20.0.11"]
}

After sudo systemctl restart docker, docker run --rm alpine nslookup nexus.corp.internal resolved correctly and pulls succeeded. The root cause was a stale public-DNS override that could never resolve internal names — the typo hypothesis was ruled out early because the shell resolved the name fine.

Prevention Best Practices

• Double-check registry hostnames in image references and CI variables; NXDOMAIN is most often a typo or a decommissioned domain.
• Set an explicit, correct dns list in /etc/docker/daemon.json on hosts that depend on internal or split-horizon DNS rather than relying on inherited resolv.conf.
• Keep public-DNS overrides (8.8.8.8, 1.1.1.1) out of daemon.json on machines that must reach internal registries — they silently break internal resolution.
• Ensure the VPN/network zone that hosts a private registry is up before pulling, and document which registries live behind which networks.
• Validate daemon.json with jq . /etc/docker/daemon.json before restarting so a bad edit doesn’t compound the outage.

Quick Command Reference

# Does the name resolve at the OS level?
getent hosts <registry>
dig +short <registry>

# Does it resolve inside Docker's embedded resolver?
docker run --rm alpine nslookup <registry>
docker run --rm alpine cat /etc/resolv.conf

# What DNS does the host / daemon use?
cat /etc/resolv.conf
journalctl -u docker --since '10 min ago' | grep -i 'no such host'

# Set daemon upstream DNS, then restart
sudo nano /etc/docker/daemon.json     # add {"dns": ["10.0.0.2","1.1.1.1"]}
jq . /etc/docker/daemon.json
sudo systemctl restart docker

# One-off per-container override
docker run --dns 10.0.0.2 --rm alpine nslookup <registry>

Conclusion

lookup <registry> on 127.0.0.11:53: no such host means Docker’s embedded resolver forwarded your query upstream and got NXDOMAIN back — the name does not exist for that resolver. Start by ruling out a typo with getent/dig, then check whether the daemon’s upstream DNS can actually serve the record. On corporate and split-horizon networks the fix is almost always pointing daemon.json’s dns list at the resolver that knows your internal zone, not a public one. Because this is NXDOMAIN and not a timeout, it is a resolution-content problem, not a reachability one — treat it differently from temporary failure in name resolution.