{"record":{"id":"6c09c8ac3f504823","repo":"docker/compose","slug":"warning-the-q-service-is-using-the-custom-contai","errorCode":null,"errorMessage":"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","messagePattern":"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","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/compose/convergence.go","lineNumber":55,"sourceCode":"\n\t\"github.com/docker/compose/v5/pkg/api\"\n)\n\nconst (\n\tdoubledContainerNameWarning = \"WARNING: The %q service is using the custom container name %q. \" +\n\t\t\"Docker requires each container to have a unique name. \" +\n\t\t\"Remove the custom name to scale the service\"\n)\n\n// convergence manages service's container lifecycle.\n// Based on initially observed state, it reconciles the existing container with desired state, which might include\n// re-creating container, adding or removing replicas, or starting stopped containers.\n// Cross services dependencies are managed by creating services in expected order and updating `service:xx` reference\n// when a service has converged, so dependent ones can be managed with resolved containers references.\nfunc getScale(config types.ServiceConfig) (int, error) {\n\tscale := config.GetScale()\n\tif scale > 1 && config.ContainerName != \"\" {\n\t\treturn 0, fmt.Errorf(doubledContainerNameWarning,\n\t\t\tconfig.Name,\n\t\t\tconfig.ContainerName)\n\t}\n\treturn scale, nil\n}\n\n// resolveServiceReferences replaces references to other services with references\n// to actual container IDs. It resolves VolumesFrom, NetworkMode, IPC and PID\n// shared namespaces. The containersByService map provides the observed containers\n// grouped by service name.\nfunc resolveServiceReferences(service *types.ServiceConfig, containersByService map[string]Containers) error {\n\tif err := resolveVolumeFrom(service, containersByService); err != nil {\n\t\treturn err\n\t}\n\treturn resolveSharedNamespaces(service, containersByService)\n}\n\nfunc resolveVolumeFrom(service *types.ServiceConfig, containersByService map[string]Containers) error {","sourceCodeStart":37,"sourceCodeEnd":73,"githubUrl":"https://github.com/docker/compose/blob/ddc4b044b62e9f715212ea4143fa830fac76382f/pkg/compose/convergence.go#L37-L73","documentation":"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.","triggerScenarios":"`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.","commonSituations":"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.","solutions":["Remove `container_name:` from the service so replicas get generated names (project-service-N)","Or keep the custom name but force scale to 1 (drop --scale / replicas)","If a stable hostname is why the name was pinned, use a network alias or explicit `hostname:` per replica instead of container_name"],"exampleFix":"# before\nservices:\n  web:\n    container_name: myweb\n    scale: 3   # -> error\n\n# after\nservices:\n  web:\n    scale: 3","handlingStrategy":"validation","validationCode":"if svc.GetScale() > 1 && svc.ContainerName != \"\" {\n    return fmt.Errorf(\"service %s: remove container_name %q before scaling to %d\",\n        svc.Name, svc.ContainerName, svc.GetScale())\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never combine container_name with scale/replicas in Compose files","Use `docker compose config` as a CI lint step to catch scale+name conflicts before deploy"],"tags":["scale","container-name","configuration","replicas"],"backgroundTag":null,"analyzedSha":"ddc4b044b62e9f715212ea4143fa830fac76382f","analyzedAt":"2026-08-15T13:31:42.319Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}