{"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":633,"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":615,"sourceCodeEnd":651,"githubUrl":"https://github.com/docker/cli/blob/e9452d6e785f6e365712b9d71bd7517591773c86/cli/command/service/opts.go#L615-L651","documentation":"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.","triggerScenarios":"`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.","commonSituations":"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.","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."],"exampleFix":"# before\ndocker service create --mode global --replicas-max-per-node 2 nginx\n# after\ndocker service create --mode replicated --replicas 6 --replicas-max-per-node 2 nginx","handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":["docker","swarm","cli","placement","flag-validation"],"analyzedSha":"e9452d6e785f6e365712b9d71bd7517591773c86","analyzedAt":"2026-08-01T07:09:22.474Z","schemaVersion":2}