When Docker DNS stops making sense

A connection error is not always a DNS error. Before changing resolvers, separate the problem into smaller questions: can the name resolve, can the destination be reached, and is anything listening there?

Check from the right place

A successful lookup on the host does not prove that the same name resolves inside a container. Inspect the affected service from its own network context.

docker compose exec app cat /etc/resolv.conf
docker network inspect your_network

Replace the service and network names with your own. Minimal container images may not contain a shell or lookup utilities; use a disposable diagnostic container on the same network if needed.

Know which network you are using

Docker treats its default bridge differently from user-defined networks. Containers on a custom network use Docker's embedded DNS resolver, which can resolve container names on that network and forward external queries.

If two Compose services should find each other, first check that they share the intended network. Use the service name and the container port for service-to-service traffic. A port published on the host is a different route into the service.

A useful order of operations

1. Confirm the hostname is the one the application is actually using.
2. Inspect the networks attached to both containers.
3. Test name resolution in the affected network context.
4. Test the destination port separately.
5. Read the receiving application's logs.

Avoid changing several layers at once. A resolver change, a container restart, and a firewall edit might fix something, but they make it much harder to know which thing mattered.

The boring conclusion is often the useful one: a wrong service name, a missing network, or a process bound to the wrong interface.

Reference: Docker networking — DNS services.