{"id":"771a3dc9e5f47204","repo":"docker/cli","slug":"replicas-can-only-be-used-with-replicated-mode","errorCode":null,"errorMessage":"replicas can only be used with replicated mode","messagePattern":"replicas can only be used with replicated mode","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/service/update.go","lineNumber":1138,"sourceCode":"func equalProtocol(prot1, prot2 network.IPProtocol) bool {\n\treturn prot1 == prot2 ||\n\t\t(prot1 == \"\" && prot2 == network.TCP) ||\n\t\t(prot2 == \"\" && prot1 == network.TCP)\n}\n\nfunc equalPublishMode(mode1, mode2 swarm.PortConfigPublishMode) bool {\n\treturn mode1 == mode2 ||\n\t\t(mode1 == \"\" && mode2 == swarm.PortConfigPublishModeIngress) ||\n\t\t(mode2 == \"\" && mode1 == swarm.PortConfigPublishModeIngress)\n}\n\nfunc updateReplicas(flags *pflag.FlagSet, serviceMode *swarm.ServiceMode) error {\n\tif !flags.Changed(flagReplicas) {\n\t\treturn nil\n\t}\n\n\tif serviceMode == nil || serviceMode.Replicated == nil {\n\t\treturn errors.New(\"replicas can only be used with replicated mode\")\n\t}\n\tserviceMode.Replicated.Replicas = flags.Lookup(flagReplicas).Value.(*Uint64Opt).Value()\n\treturn nil\n}\n\ntype hostMapping struct {\n\tIPAddr string\n\tHost   string\n}\n\n// updateHosts performs a diff between existing host entries, entries to be\n// removed, and entries to be added. Host entries preserve the order in which they\n// were added, as the specification mentions that in case multiple entries for a\n// host exist, the first entry should be used (by default).\n//\n// Note that, even though unsupported by the CLI, the service specs format\n// allow entries with both a _canonical_ hostname, and one or more aliases\n// in an entry (IP-address canonical_hostname [alias ...])","sourceCodeStart":1120,"sourceCodeEnd":1156,"githubUrl":"https://github.com/docker/cli/blob/e9452d6e785f6e365712b9d71bd7517591773c86/cli/command/service/update.go#L1120-L1156","documentation":"Emitted by `docker service update --replicas`. updateReplicas (update.go:1132-1141) only applies when the flag changed; it then requires Spec.Mode.Replicated to be non-nil. Global, global-job, and replicated-job services fail here — global modes have no replica count, and replicated jobs are sized via --max-concurrent/total completions rather than --replicas.","triggerScenarios":"`docker service update --replicas N <svc>` on a service whose mode is global, global-job, or replicated-job (serviceMode.Replicated == nil at update time).","commonSituations":"Attempting to scale a global agent/daemonset-style service; compose-deployed services with `deploy.mode: global`; confusing `docker service update --replicas` with `docker service scale` semantics on job services.","solutions":["Verify the mode: `docker service inspect --format '{{json .Spec.Mode}}' <svc>`; for global services replica count is one-per-node by design","For replicated-job services use `docker service scale <svc>=N` (which sets TotalCompletions) instead of --replicas","If replicated behavior is wanted, recreate the service with `--mode replicated` — mode cannot be changed via update"],"exampleFix":"# before\ndocker service update --replicas 5 global-agent   # fails\n\n# after (service recreated as replicated)\ndocker service create --mode replicated --replicas 5 --name agent myimg","handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":["swarm","service","update","replicas","service-mode"],"analyzedSha":"e9452d6e785f6e365712b9d71bd7517591773c86","analyzedAt":"2026-08-01T07:09:22.474Z","schemaVersion":2}