{"record":{"id":"2a866fb77b94b37c","repo":"docker/cli","slug":"max-concurrent-can-only-be-used-with-replicated-jo","errorCode":null,"errorMessage":"max-concurrent can only be used with replicated-job mode","messagePattern":"max-concurrent can only be used with replicated-job mode","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/service/opts.go","lineNumber":637,"sourceCode":"\t\tcapAdd:          opts.NewListOpts(nil),\n\t\tcapDrop:         opts.NewListOpts(nil),\n\t\tulimits:         *opts.NewUlimitOpt(nil),\n\t}\n}\n\nfunc (options *serviceOptions) ToServiceMode() (swarm.ServiceMode, error) {\n\tserviceMode := swarm.ServiceMode{}\n\tswitch options.mode {\n\tcase \"global\":\n\t\tif options.replicas.Value() != nil {\n\t\t\treturn serviceMode, errors.New(\"replicas can only be used with replicated or replicated-job mode\")\n\t\t}\n\n\t\tif options.maxReplicas > 0 {\n\t\t\treturn serviceMode, errors.New(\"replicas-max-per-node can only be used with replicated or replicated-job mode\")\n\t\t}\n\t\tif options.maxConcurrent.Value() != nil {\n\t\t\treturn serviceMode, errors.New(\"max-concurrent can only be used with replicated-job mode\")\n\t\t}\n\n\t\tserviceMode.Global = &swarm.GlobalService{}\n\tcase \"replicated\":\n\t\tif options.maxConcurrent.Value() != nil {\n\t\t\treturn serviceMode, errors.New(\"max-concurrent can only be used with replicated-job mode\")\n\t\t}\n\n\t\tserviceMode.Replicated = &swarm.ReplicatedService{\n\t\t\tReplicas: options.replicas.Value(),\n\t\t}\n\tcase \"replicated-job\":\n\t\tconcurrent := options.maxConcurrent.Value()\n\t\tif concurrent == nil {\n\t\t\tconcurrent = options.replicas.Value()\n\t\t}\n\t\tserviceMode.ReplicatedJob = &swarm.ReplicatedJob{\n\t\t\tMaxConcurrent:    concurrent,","sourceCodeStart":619,"sourceCodeEnd":655,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/service/opts.go#L619-L655","documentation":"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.","triggerScenarios":"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.","commonSituations":"A developer experimenting with job flags on a non-job service, or a script that sets `--max-concurrent` unconditionally for all services.","solutions":["Remove `--max-concurrent` when using `--mode global`","Switch to `--mode replicated-job` to use `--max-concurrent` (it controls concurrent job task execution)"],"exampleFix":"# before\ndocker service create --mode global --max-concurrent 5 --image myjob web\n# error: max-concurrent can only be used with replicated-job mode\n\n# after\ndocker service create --mode global --image myjob web\n# or for jobs:\ndocker service create --mode replicated-job --max-concurrent 5 --replicas 20 --image myjob web","handlingStrategy":"validation","validationCode":"// Validate maxConcurrent with mode\nfunc validateMaxConcurrentWithMode(mode string, maxConcurrent *uint64) error {\n    if mode != \"replicated-job\" && maxConcurrent != nil {\n        return errors.New(\"max-concurrent can only be used with replicated-job mode\")\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["--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"],"tags":["docker","cli","service","swarm","mode-conflict","flag-validation","job"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}