docker compose rejects replicas in the compose file
Additional property replicas is not allowedShort answer
The Compose schema accepts replicas only inside the deploy section of a service, not directly under the service. Move it there, with mode left as replicated. Run docker compose config to validate the file. If you need several copies, do not set container_name, since Compose cannot scale a named container.
Fix it fast
1Find out which cause you have
Validate the file. The output names the service and key that Compose could not accept; -q prints nothing if the file is fine.
docker compose config -q2Match what you see, then jump to its fix
- 1
The error names the service, and replicas sits at the same indentation as imagereplicas is written directly under the serviceFix - 2
The deploy block has mode: global and also a replicas count, so the count has no effectreplicas is used with global modeFix - 3
The file is valid but starting several copies failscontainer_name stops the service from scalingFix
- 1
What does the error look like?
Additional property replicas is not alloweddocker compose config fails on a file that has a replicas key
Cause 1 of 3
replicas is written directly under the service
1Check
In the Compose Specification, replicas belongs to the deploy section of a service.
grep -n -B3 -A3 "replicas" compose.yaml2Fix
Nest replicas under deploy. With the default replicated mode it sets how many containers should be running.
services:
web:
image: example/webapp
deploy:
mode: replicated
replicas: 33Verify
Validation prints nothing, and the rendered file shows the replicas under deploy.
docker compose config -q
docker compose config | grep -A3 deployConfirmed by docs.docker.com
Cause 2 of 3
replicas is used with global mode
1Check
global and global-job modes do not use replicas; they run one task per node.
grep -n -A4 "deploy:" compose.yaml2Fix
Use replicated mode (the default) when you want a number of copies, and remove replicas if you want global.
deploy:
mode: replicated
replicas: 33Verify
Run the validation again.
docker compose config -qConfirmed by docs.docker.com
Cause 3 of 3
container_name stops the service from scaling
1Check
Compose will not scale a service beyond one container when container_name is set, and a scaling attempt gives an error.
grep -n "container_name" compose.yaml2Fix
Remove container_name from the service so Compose can name each copy itself. If you also set scale, keep it equal to replicas.
services:
web:
image: example/webapp
scale: 3
deploy:
replicas: 33Verify
Start the stack and count the containers.
docker compose up -d
docker compose psConfirmed by docs.docker.com
How do I stop it coming back?
- Run docker compose config -q in CI so a bad file fails before it ships.
- Remove the top-level version key: it is obsolete and only produces a warning.
- Keep one way of setting the copy count, either deploy.replicas or scale.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Servers
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fixServers
sam local fails: Running AWS SAM projects locally requires Docker
Cannot connect to the Docker daemon. Is the docker daemon running on this host?
sam local start-api and sam local invoke run your function inside a Docker container, so SAM stops if it cannot talk to Docker.
3 causes, each with a fixServers
dnf fails to download repo metadata in a CentOS 8 Docker build
The same Dockerfile built fine before 2022
CentOS Linux 8 reached end of life on 31 December 2021 and its content left the mirrors.
2 causes, each with a fixServers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
Cypress says the npm package is installed but the binary is missing
Cypress binary is missing after npm install in CI or in a Docker build
The npm package is only a launcher.
3 causes, each with a fixServers
A dev container port does not open in the browser when Docker runs on a remote host
If your application only accepts calls from localhost, it will reject connections from published ports
Three things usually break it: the app listens only on localhost inside the container, so published ports are rejected; you open the container port instead of the mapped localhost port VS Code shows; or you changed appPort or a Compose ports list and did not rebuild.
3 causes, each with a fix