16.4.2.1 Compose Wrong Service Name

A Compose wrong service name error occurs when a reference within a Compose file, in depends_on, an environment variable, or an application's own configuration, points at a name that does not actually correspond to how Compose has made that service discoverable on the network, which is a distinct and sometimes confusing category of mistake once container_name, scaling, or multiple naming conventions enter the picture.

Service name versus container name

Compose's automatic DNS-based service discovery resolves by service name, the key used in the services section of the Compose file, not by whatever the actual container ends up named, which only matters once an explicit container_name override is introduced and diverges from the service name itself:

services:
  database:
    image: postgres
    container_name: my-custom-db-name

docker compose exec api ping database

docker compose exec api ping my-custom-db-name

Both of these actually work in most current Compose versions, since Compose registers both the service name and, separately, the explicit container name as resolvable hostnames on the network; but relying on the explicit container name specifically, rather than the underlying service name, ties application configuration to an additional, separate naming detail that adds a maintenance burden if that name is ever changed later without a corresponding update everywhere it was referenced.

Container name uniqueness conflicts with scaling

Explicitly setting container_name for a service prevents that service from being scaled to more than one replica, since container names must be unique and Compose cannot create multiple containers sharing the identical, explicitly fixed name:

services:
  api:
    container_name: my-api

docker compose up -d --scale api=3

ERROR: for api  Cannot create container for service api: Conflict. The container name "/my-api" is already in use

Removing the explicit container_name and relying on Compose's own automatically generated, unique container names per replica resolves this, restoring the ability to scale the service while still allowing the service name itself to continue resolving correctly through Compose's own DNS mechanism.

Service name resolution with multiple replicas

When a service is scaled to more than one replica, its service name resolves to multiple addresses, one per running replica, and a client performing a standard DNS lookup typically receives all of them, with the specific one actually used for a given connection depending on the client's own DNS resolution behavior, often a simple round-robin or first-result selection rather than genuine load balancing:

docker compose up -d --scale api=3
docker compose exec worker getent hosts api

172.18.0.3   api
172.18.0.4   api
172.18.0.5   api

A client connecting to api here may or may not actually distribute its connections evenly across all three replicas, depending entirely on how its own networking and DNS resolution library behaves; for genuine, deliberate load balancing across replicas, a dedicated reverse proxy or load balancer service, rather than relying on this DNS-based behavior directly, is the more predictable and controllable approach.

Typos and inconsistent naming between configuration sections

A reference to a service name in depends_on, an environment variable's connection string, or a health check command needs to match the actual service key exactly, including case, and a small, easy-to-overlook discrepancy between these different places a service might be referenced produces a clear resolution failure at exactly the point of mismatch:

services:
  Database:
    image: postgres
  api:
    environment:
      - DATABASE_URL=postgres://database:5432/app

Compose service names are generally treated case-sensitively for DNS resolution purposes in most environments, which means a reference to database (lowercase) does not resolve correctly if the actual service key is defined as Database (capitalized); keeping naming consistently lowercase throughout a Compose file avoids this entire class of subtle mismatch.

Renaming a service and updating every reference

When a service is renamed within a Compose file, every other place that name appears, depends_on entries, environment variable values referencing it by hostname, health check commands checking connectivity to it, needs to be updated consistently, since Compose itself does not track or automatically propagate a rename across these separate, independent references:

grep -rn "old-service-name" docker-compose.yml docker-compose.*.yml

Searching explicitly across every Compose file and override for the old name, after a rename, catches any reference that was missed in the initial change, before it causes a confusing resolution failure later.

Cross-stack service name references

A service name from one Compose project is not resolvable from a different Compose project's services unless they have been explicitly connected through a shared, external network; assuming a service name will resolve simply because it exists somewhere on the same host, without that explicit shared network connection, produces a resolution failure that looks identical to a simple naming mistake but actually stems from project-level network isolation:

docker network connect myproject_default otherproject_api_1

Confirming both services are genuinely on a network together, as covered more generally in Compose communication troubleshooting, resolves this distinct but related category of apparent naming issue.

Common mistakes

• Relying on an explicit container_name for service-to-service communication, creating an additional naming dependency and preventing that service from ever being scaled to multiple replicas.
• Assuming DNS resolution against a scaled service's name provides genuine, even load balancing across replicas, rather than recognizing this depends entirely on client-side DNS resolution behavior.
• Introducing a case mismatch between a Compose service's defined key and how it is referenced elsewhere in environment variables or other configuration.
• Renaming a service without searching the entire Compose file and any override files for every other place the old name was referenced.
• Assuming a service name will resolve across two genuinely separate Compose projects without an explicit, shared network connecting them.

Compose wrong service name issues are resolved by consistently using the actual service key, rather than an explicit container name, as the basis for inter-service communication, keeping naming case-consistent throughout the file, and searching thoroughly across every configuration file whenever a service is renamed to ensure every reference to it was updated together.