{"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":629,"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":611,"sourceCodeEnd":647,"githubUrl":"https://github.com/docker/cli/blob/e9452d6e785f6e365712b9d71bd7517591773c86/cli/command/service/opts.go#L611-L647","documentation":"Raised by serviceOptions.ToServiceMode in the Docker CLI when a service is created or updated with mode 'global' but the --replicas flag was set. Global mode runs exactly one task per active node, so an explicit replica count is contradictory; the CLI rejects the combination client-side before contacting the Swarm API.","triggerScenarios":"Running `docker service create --mode global --replicas N ...` or `docker service update` on a global service with --replicas set; any code path calling ToServiceMode with options.mode=='global' and a non-nil replicas value.","commonSituations":"Copying a compose/service command written for replicated mode and only changing --mode to global; scripts that always pass --replicas regardless of mode; assuming global mode accepts a replica cap.","solutions":["Remove the --replicas flag when using --mode global (task count is determined by node count).","If you need a specific number of replicas, use --mode replicated (the default) with --replicas N.","For a fixed-count one-shot workload, use --mode replicated-job with --replicas N."],"exampleFix":"# before\ndocker service create --mode global --replicas 3 nginx\n# after\ndocker service create --mode replicated --replicas 3 nginx","handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":["docker","swarm","cli","service-mode","flag-validation"],"analyzedSha":"e9452d6e785f6e365712b9d71bd7517591773c86","analyzedAt":"2026-08-01T07:09:22.474Z","schemaVersion":2}