max-concurrent can only be used with replicated-job mode

Error message

max-concurrent can only be used with replicated-job mode

What it means

Raised in ToServiceMode when --max-concurrent is set (options.maxConcurrent.Value() != nil) while mode is 'global'. Max-concurrent limits how many job tasks run simultaneously and only applies to replicated-job services; a global service is a long-running per-node service with no concurrency window.

Source

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

		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()
		}
		serviceMode.ReplicatedJob = &swarm.ReplicatedJob{
			MaxConcurrent:    concurrent,

View on GitHub (pinned to e9452d6e78)

Solutions

Use --mode replicated-job if you want a batch job with limited concurrency (--max-concurrent N).
If you meant to throttle rolling updates of a service, use --update-parallelism instead.
Otherwise remove --max-concurrent from the global-mode command.

Example fix

# before
docker service create --mode global --max-concurrent 2 my-batch
# after
docker service create --mode replicated-job --replicas 10 --max-concurrent 2 my-batch

When it happens

Trigger: `docker service create --mode global --max-concurrent N ...`; ToServiceMode with mode=='global' and a non-nil maxConcurrent.

Common situations: Confusing global services with global-job batch workloads; reusing a replicated-job command line after changing the mode; assuming max-concurrent throttles rollout like update-parallelism.

Related errors

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