docker/compose · error

WARNING: The %q service is using the custom container name %

Error message

WARNING: The %q service is using the custom container name %q. Docker requires each container to have a unique name. Remove the custom name to scale the service

What it means

getScale rejects a configuration contradiction: the service requests scale > 1 while also pinning an explicit container_name. Docker requires unique container names, so multiple replicas of a named container cannot coexist; despite the WARNING-style wording this is returned as a hard error before convergence starts.

Source

Thrown at pkg/compose/convergence.go:55

	"github.com/docker/compose/v5/pkg/api"
)

const (
	doubledContainerNameWarning = "WARNING: The %q service is using the custom container name %q. " +
		"Docker requires each container to have a unique name. " +
		"Remove the custom name to scale the service"
)

// convergence manages service's container lifecycle.
// Based on initially observed state, it reconciles the existing container with desired state, which might include
// re-creating container, adding or removing replicas, or starting stopped containers.
// Cross services dependencies are managed by creating services in expected order and updating `service:xx` reference
// when a service has converged, so dependent ones can be managed with resolved containers references.
func getScale(config types.ServiceConfig) (int, error) {
	scale := config.GetScale()
	if scale > 1 && config.ContainerName != "" {
		return 0, fmt.Errorf(doubledContainerNameWarning,
			config.Name,
			config.ContainerName)
	}
	return scale, nil
}

// resolveServiceReferences replaces references to other services with references
// to actual container IDs. It resolves VolumesFrom, NetworkMode, IPC and PID
// shared namespaces. The containersByService map provides the observed containers
// grouped by service name.
func resolveServiceReferences(service *types.ServiceConfig, containersByService map[string]Containers) error {
	if err := resolveVolumeFrom(service, containersByService); err != nil {
		return err
	}
	return resolveSharedNamespaces(service, containersByService)
}

func resolveVolumeFrom(service *types.ServiceConfig, containersByService map[string]Containers) error {

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Remove `container_name:` from the service so replicas get generated names (project-service-N)
2. Or keep the custom name but force scale to 1 (drop --scale / replicas)
3. If a stable hostname is why the name was pinned, use a network alias or explicit `hostname:` per replica instead of container_name

Example fix

# before
services:
  web:
    container_name: myweb
    scale: 3   # -> error

# after
services:
  web:
    scale: 3

if svc.GetScale() > 1 && svc.ContainerName != "" {
    return fmt.Errorf("service %s: remove container_name %q before scaling to %d",
        svc.Name, svc.ContainerName, svc.GetScale())
}

When it happens

Trigger: `docker compose up --scale web=3` (or `deploy.replicas`/`scale` in the file) on a service that also sets `container_name: web`. Also hit via `docker compose run`/recreate flows that call getScale for a named service with replicas > 1.

Common situations: Adding `--scale` in CI or orchestration on top of a hand-written file that pins container_name for DNS/alias reasons; merging a swarm-style file with replicas into Compose; legacy v2 files where container_name was common.

Related errors

• failed to parse env_file %s: %w
• %s must be an integer (found: %q)
• invalid --scale option %q. Should be SERVICE=NUM
• invalid scale specifier: %s
• invalid scale specifier: can't parse replica value as int: %

AI-assisted analysis of docker/compose@ddc4b044b6 (2026-08-15). Data as JSON: /api/errors/6c09c8ac3f504823. Report an issue: GitHub.