{"record":{"id":"c73a9421fe54bcbc","repo":"docker/cli","slug":"replicas-max-per-node-can-only-be-used-with-replic","errorCode":null,"errorMessage":"replicas-max-per-node can only be used with replicated or replicated-job mode","messagePattern":"replicas-max-per-node can only be used with replicated or replicated-job mode","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/service/opts.go","lineNumber":634,"sourceCode":"\t\tdnsSearch:       opts.NewListOpts(opts.ValidateDNSSearch),\n\t\thosts:           opts.NewListOpts(opts.ValidateExtraHost),\n\t\tsysctls:         opts.NewListOpts(nil),\n\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()","sourceCodeStart":616,"sourceCodeEnd":652,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/service/opts.go#L616-L652","documentation":"In `ToServiceMode()`, the `--mode global` case at opts.go:633-634 also checks `--replicas-max-per-node` (`options.maxReplicas > 0`). Global services run one task per node by definition, so capping tasks per node is not applicable. This fires when the `--replicas-max-per-node` flag is set to a value greater than zero alongside `--mode global`.","triggerScenarios":"Running `docker service create --mode global --replicas-max-per-node 2 --image nginx web`. The `--replicas-max-per-node` flag maps to `options.maxReplicas` (line 915), which defaults to 0 (unlimited); any non-zero value with global mode triggers this error.","commonSituations":"A developer migrates from replicated mode and leaves the `--replicas-max-per-node` flag in place, or sets it globally in a script for all services.","solutions":["Remove `--replicas-max-per-node` when using `--mode global`","Switch to `--mode replicated` or `--mode replicated-job` to use this flag"],"exampleFix":"# before\ndocker service create --mode global --replicas-max-per-node 2 --image nginx web\n# error: replicas-max-per-node can only be used with replicated or replicated-job mode\n\n# after\ndocker service create --mode global --image nginx web","handlingStrategy":"validation","validationCode":"// Validate maxReplicas with mode\nfunc validateMaxReplicasWithMode(mode string, maxReplicas uint64) error {\n    if (mode == \"global\" || mode == \"global-job\") && maxReplicas > 0 {\n        return errors.New(\"replicas-max-per-node can only be used with replicated or replicated-job mode\")\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["--replicas-max-per-node is only valid for replicated and replicated-job modes","Global modes run one task per node by definition — per-node caps are redundant","Use mode-conditional flag logic in deployment scripts"],"tags":["docker","cli","service","swarm","mode-conflict","flag-validation"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}