replicas-max-per-node can only be used with replicated or re

Error message

replicas-max-per-node can only be used with replicated or replicated-job mode

What it means

Raised in ToServiceMode when --replicas-max-per-node (options.maxReplicas > 0) is combined with mode 'global'. Max-replicas-per-node is a placement constraint meaningful only when the scheduler distributes a replica pool; global mode always places exactly one task per node, so the flag is rejected.

Source

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

		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(),
		}
	case "replicated-job":
		concurrent := options.maxConcurrent.Value()
		if concurrent == nil {
			concurrent = options.replicas.Value()

View on GitHub (pinned to e9452d6e78)

Solutions

Drop --replicas-max-per-node for global-mode services; it already runs one task per node.
Switch to --mode replicated (or replicated-job) if you want a replica pool spread with a per-node cap.

Example fix

# before
docker service create --mode global --replicas-max-per-node 2 nginx
# after
docker service create --mode replicated --replicas 6 --replicas-max-per-node 2 nginx

When it happens

Trigger: `docker service create --mode global --replicas-max-per-node N ...` or updating a global service with that flag; ToServiceMode with mode=='global' and maxReplicas>0.

Common situations: Trying to limit tasks per node on a global service (redundant — it's always 1); templated deploy scripts applying placement flags uniformly across services of different modes.

Related errors

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