Context
A container name is not a universal hostname. Docker provides automatic name and alias resolution on user-defined bridge networks, while the default bridge behaves differently. Two containers can run on the same host and still have no shared name-resolution context. Begin with network membership rather than adding arbitrary entries to hosts files.
You need the calling container, destination container, expected network, and application listener port. Read-only inspection is sufficient for the first pass. Use an existing diagnostic tool inside the caller or an approved disposable test container on the same network; do not install packages into a production container during diagnosis.
1. Compare actual network attachments
docker container inspect --format '{{json .NetworkSettings.Networks}}' web
docker container inspect --format '{{json .NetworkSettings.Networks}}' api
docker network inspect app-network
All names are illustrative. Confirm that both containers share the intended user-defined network and that the destination has the expected alias there. An alias attached on another network does not automatically apply to the caller's network. A recreated container may also have a different IP, which is why recording and hardcoding yesterday's address is a fragile correction.
2. Test resolution from the caller
docker exec web cat /etc/resolv.conf
docker exec web getent hosts api
Use equivalent supported tools if getent is absent. Containers on custom networks commonly use Docker's embedded resolver, which forwards external lookups through configured upstream settings. Container-name resolution and public DNS resolution are related but distinct checks. A successful lookup for an internet hostname does not establish that api is an alias on the shared Docker network.
For an explicitly illustrative example, web is attached to app-network, while api was launched on the default bridge. The host can reach api through a published port, yet web cannot resolve api as a network peer. The missing shared network membership explains this difference without requiring a public DNS record.
3. Verify the destination port and listener
After resolution succeeds, issue a harmless application request to the destination's container port from the caller. Published host ports serve a different access path. If api listens on 8080 internally and publishes host port 18080, another container on the shared network normally uses api:8080.
Also confirm the process listens on the appropriate container interface. An application bound only to its own loopback address cannot receive connections directed to the container's network address. Inside web, localhost refers to web's own network namespace, not to api or the Docker host.
Interpret the result before changing configuration
| Observation | Likely boundary | Next check |
|---|---|---|
| Name absent, containers share no custom network | Discovery scope | Network attachments and aliases |
| Name resolves, connection refused | Destination listener | Internal port and bind address |
| Public names fail, container names work | Upstream DNS | Resolver and host DNS configuration |
| Address changes after recreation | Ephemeral addressing | Replace hardcoded IP with managed name |
Avoid legacy link-based workarounds for a new design. Review the application network declaration so the intended membership survives recreation. Connecting a container to an additional network can change its reachable peers, so treat that as a deliberate configuration change.
Verify and maintain the network contract
Apply the reviewed network or application-listener correction through the normal deployment configuration. Recreate the representative test stack and repeat resolution plus the harmless request from the caller. This checks persistence of the fix rather than a one-time manual attachment.
Document network name, caller, destination alias, internal port, published access path, and owner. Monitor application connection failures with destination names and port context. Recheck the contract after deployment-tool changes, because a healthy process and a working host port do not prove container-to-container discovery.
Explore Clouvenix docker consulting for implementation and operational handover.