7.3.2.2 Wrong Service Name

A wrong service name mistake occurs when an application is configured to look up a dependent service by a name that doesn't actually match the target container's real name or configured network alias, producing a resolution failure even when both containers correctly share a resolving network.

How This Mistake Typically Happens

A typo, an outdated configuration value, or a mismatch between an application's expected service name and the container's actual name all lead to the same underlying problem.

docker network create app-network
docker run -d --name database --network app-network postgres:16
docker run -d --name api --network app-network -e DATABASE_HOST=db myapi:1.0

Here, api is configured to look for a service named db, but the actual container is named database — these don't match, so resolution fails despite both containers correctly sharing app-network.

Confirming This Is the Actual Cause

Checking the actual container name (and any configured aliases) against what the application is actually configured to look up reveals this specific mismatch.

docker ps --format '{{.Names}}'
docker exec api env | grep DATABASE_HOST

Comparing these directly reveals the discrepancy between the expected and actual service name.

The Fix: Aligning the Configured Name With the Actual Container Name

Either renaming the container or adjusting the application's configuration to use the correct name resolves the mismatch.

docker run -d --name db --network app-network postgres:16

docker run -d --name api --network app-network -e DATABASE_HOST=database myapi:1.0

Either approach resolves the mismatch, depending on which side is more convenient to adjust.

Using a Network Alias as a More Robust Alternative

Assigning a network alias matching the expected name provides another path to resolution, without needing to rename the actual container.

docker run -d --name database --network app-network --network-alias db postgres:16

Why Recognizing This Mistake Matters

Because this mistake produces the exact same resolution failure symptom as containers being on different networks entirely, explicitly comparing the configured expected name against the actual container name (or alias) is a necessary, distinct troubleshooting step from simply confirming shared network membership.