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

In `ToServiceMode()`, the `--mode global` case at opts.go:636-637 checks `--max-concurrent` (`options.maxConcurrent.Value() != nil`). The `--max-concurrent` flag controls how many job tasks run simultaneously and is only valid for `replicated-job` mode. Using it with global mode is a semantic error.

Solutions

Remove `--max-concurrent` when using `--mode global`
Switch to `--mode replicated-job` to use `--max-concurrent` (it controls concurrent job task execution)

Example fix

# before
docker service create --mode global --max-concurrent 5 --image myjob web
# error: max-concurrent can only be used with replicated-job mode

# after
docker service create --mode global --image myjob web
# or for jobs:
docker service create --mode replicated-job --max-concurrent 5 --replicas 20 --image myjob web

Defensive patterns

Strategy: validation

Validate before calling

// Validate maxConcurrent with mode
func validateMaxConcurrentWithMode(mode string, maxConcurrent *uint64) error {
    if mode != "replicated-job" && maxConcurrent != nil {
        return errors.New("max-concurrent can only be used with replicated-job mode")
    }
    return nil
}

Prevention

--max-concurrent is exclusively a replicated-job flag — it controls concurrent job task execution
Global and replicated modes do not support job concurrency limiting
Only apply job-specific flags (--max-concurrent, --replicas for jobs) when mode is replicated-job

When it happens

Trigger: Running `docker service create --mode global --max-concurrent 5 --image nginx web`. The `--max-concurrent` flag is registered at line 913 and version-annotated as 1.41.

Common situations: A developer experimenting with job flags on a non-job service, or a script that sets `--max-concurrent` unconditionally for all services.

Related errors

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/2a866fb77b94b37c. Report an issue: GitHub.

Appendix: source

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

		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 4f84911bfe)