{"record":{"id":"fe1798b0af655a23","repo":"docker/cli","slug":"replicas-can-only-be-used-with-replicated-or-repli","errorCode":null,"errorMessage":"replicas can only be used with replicated or replicated-job mode","messagePattern":"replicas 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":630,"sourceCode":"\t\tgroups:          opts.NewListOpts(nil),\n\t\tlogDriver:       newLogDriverOptions(),\n\t\tdns:             opts.NewListOpts(opts.ValidateIPAddress),\n\t\tdnsOption:       opts.NewListOpts(nil),\n\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}","sourceCodeStart":612,"sourceCodeEnd":648,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/service/opts.go#L612-L648","documentation":"In `serviceOptions.ToServiceMode()` at opts.go:625-631, the `--mode global` case checks whether `--replicas` was also set. Global services run exactly one task per node, so a replica count is semantically meaningless. This error fires when `options.replicas.Value() != nil` inside the `case \"global\"` branch (line 629-630).","triggerScenarios":"Running `docker service create --mode global --replicas 3 --image nginx web`. The `--replicas` flag populates `options.replicas` (a `Uint64Opt`); when mode is \"global\", any non-nil replica value triggers this error.","commonSituations":"A developer copies a `docker service create` command from a replicated template and switches `--mode` to `global` but forgets to remove `--replicas`. Or a script conditionally sets both flags.","solutions":["Remove the `--replicas` flag when using `--mode global`","Switch to `--mode replicated` if you need to specify a replica count","Use `--mode replicated-job` if you need replicas in a job context"],"exampleFix":"# before\ndocker service create --mode global --replicas 3 --image nginx web\n# error: replicas can only be used with replicated or replicated-job mode\n\n# after (global: one task per node)\ndocker service create --mode global --image nginx web\n\n# after (replicated: N tasks)\ndocker service create --mode replicated --replicas 3 --image nginx web","handlingStrategy":"validation","validationCode":"// Validate mode/flag compatibility before calling ToServiceMode\nfunc validateReplicasWithMode(mode string, replicas *uint64) error {\n    if mode == \"global\" || mode == \"global-job\" {\n        if replicas != nil {\n            return errors.New(\"replicas can only be used with replicated or replicated-job mode\")\n        }\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Global and global-job modes do not accept --replicas — remove it from templates when switching modes","Build mode-specific flag sets in deployment scripts rather than applying all flags unconditionally","Document the valid flag combinations per service mode in your team's runbook"],"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"}