7.3.2 DNS Resolution Failures

DNS resolution failures occur when a container cannot resolve another container's name to an IP address, typically because the two containers aren't actually on a shared, name-resolving network — one of the most common categories of multi-container communication problems.

Recognizing a DNS Resolution Failure

An application attempting to reach another service by name, where that name simply cannot be resolved, produces an error distinct from a connection being refused or timing out.

docker exec api ping db

ping: bad address 'db'

This specific error indicates the name itself could not be resolved at all, distinct from a successful resolution followed by a failed connection attempt.

The Most Common Underlying Cause

This failure most often occurs because the two containers aren't actually attached to the same user-defined network, or because they're both on the default bridge network, which doesn't provide this resolution at all.

docker inspect api --format '{{json .NetworkSettings.Networks}}'
docker inspect db --format '{{json .NetworkSettings.Networks}}'

Comparing these reveals whether both containers actually share a common network.

The Fix: Ensuring Both Containers Share a Network

Recreating both containers attached to the same explicit, user-defined network resolves this specific cause.

docker network create app-network
docker run -d --name db --network app-network postgres:16
docker run -d --name api --network app-network myapi:1.0
docker exec api ping db

Why This Is Such a Frequent Issue

Because it's easy to create containers without explicitly considering which network each one joins, accidentally leaving containers that need to communicate on different networks (or the non-resolving default bridge) is one of the most common multi-container setup mistakes.

Why Recognizing DNS Resolution Failures Matters

Quickly identifying this specific failure signature — name resolution itself failing, rather than a connection being refused — and checking network membership as the first diagnostic step resolves the large majority of these issues efficiently.