Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

docker compose rejects replicas in the compose file

ErrorAdditional property replicas is not allowed

Short 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.

  • Applies to Docker Compose v2, Docker Engine 28, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 -q
  2. 2Match what you see, then jump to its fix

    1. 1The error names the service, and replicas sits at the same indentation as imagereplicas is written directly under the serviceFix
    2. 2The deploy block has mode: global and also a replicas count, so the count has no effectreplicas is used with global modeFix
    3. 3The file is valid but starting several copies failscontainer_name stops the service from scalingFix

What does the error look like?

  • Additional property replicas is not allowed
  • docker 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.yaml

2Fix

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: 3

3Verify

Validation prints nothing, and the rendered file shows the replicas under deploy.

docker compose config -q
docker compose config | grep -A3 deploy

Confirmed by docs.docker.com

Did this fix it?

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.yaml

2Fix

Use replicated mode (the default) when you want a number of copies, and remove replicas if you want global.

deploy:
  mode: replicated
  replicas: 3

3Verify

Run the validation again.

docker compose config -q

Confirmed by docs.docker.com

Did this fix it?

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.yaml

2Fix

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: 3

3Verify

Start the stack and count the containers.

docker compose up -d
docker compose ps

Confirmed by docs.docker.com

Did this fix it?

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

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.