docker/cli · error

replicas can only be used with replicated or replicated-job

Error message

replicas can only be used with replicated or replicated-job mode

What it means

Raised by serviceOptions.ToServiceMode in the Docker CLI when a service is created or updated with mode 'global' but the --replicas flag was set. Global mode runs exactly one task per active node, so an explicit replica count is contradictory; the CLI rejects the combination client-side before contacting the Swarm API.

Source

Thrown at cli/command/service/opts.go:629

		groups:          opts.NewListOpts(nil),
		logDriver:       newLogDriverOptions(),
		dns:             opts.NewListOpts(opts.ValidateIPAddress),
		dnsOption:       opts.NewListOpts(nil),
		dnsSearch:       opts.NewListOpts(opts.ValidateDNSSearch),
		hosts:           opts.NewListOpts(opts.ValidateExtraHost),
		sysctls:         opts.NewListOpts(nil),
		capAdd:          opts.NewListOpts(nil),
		capDrop:         opts.NewListOpts(nil),
		ulimits:         *opts.NewUlimitOpt(nil),
	}
}

func (options *serviceOptions) ToServiceMode() (swarm.ServiceMode, error) {
	serviceMode := swarm.ServiceMode{}
	switch options.mode {
	case "global":
		if options.replicas.Value() != nil {
			return serviceMode, errors.New("replicas can only be used with replicated or replicated-job mode")
		}

		if options.maxReplicas > 0 {
			return serviceMode, errors.New("replicas-max-per-node can only be used with replicated or replicated-job mode")
		}
		if options.maxConcurrent.Value() != nil {
			return serviceMode, errors.New("max-concurrent can only be used with replicated-job mode")
		}

		serviceMode.Global = &swarm.GlobalService{}
	case "replicated":
		if options.maxConcurrent.Value() != nil {
			return serviceMode, errors.New("max-concurrent can only be used with replicated-job mode")
		}

		serviceMode.Replicated = &swarm.ReplicatedService{
			Replicas: options.replicas.Value(),
		}

View on GitHub (pinned to e9452d6e78)

Solutions

  1. Remove the --replicas flag when using --mode global (task count is determined by node count).
  2. If you need a specific number of replicas, use --mode replicated (the default) with --replicas N.
  3. For a fixed-count one-shot workload, use --mode replicated-job with --replicas N.

Example fix

# before
docker service create --mode global --replicas 3 nginx
# after
docker service create --mode replicated --replicas 3 nginx

When it happens

Trigger: Running `docker service create --mode global --replicas N ...` or `docker service update` on a global service with --replicas set; any code path calling ToServiceMode with options.mode=='global' and a non-nil replicas value.

Common situations: Copying a compose/service command written for replicated mode and only changing --mode to global; scripts that always pass --replicas regardless of mode; assuming global mode accepts a replica cap.

Related errors

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/fe1798b0af655a23.json. Report an issue: GitHub.