{"record":{"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/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/service/update.go#L1120-L1156","documentation":"Thrown by updateReplicas (cli/command/service/update.go:1138) when `--replicas` is changed but the service's Spec.Mode is nil or its Replicated field is nil. The replicas count only exists on the Replicated mode struct; global/global-job/replicated-job modes don't carry a Replicas field (replicated-job uses TotalCompletions, set via scale).","triggerScenarios":"Running `docker service update --replicas N <svc>` on a service whose mode is global, global-job, or otherwise not `replicated`. The `serviceMode.Replicated == nil` check is true and the error returns.","commonSituations":"Trying to resize a global service through update; a Compose file with `mode: global` but a deploy script that always sets replicas; mode mismatch after a partial migration.","solutions":["Recreate the service in replicated mode if a fixed replica count is desired: `docker service create --mode replicated --replicas N`.","Do not pass `--replicas` to global/global-job services; they scale with node count.","Verify the mode first: `docker service inspect --format '{{json .Spec.Mode}}' <svc>`."],"exampleFix":"// before\ndocker service update --replicas 3 myservice   # myservice is global\n\n// after\ndocker service inspect --format '{{json .Spec.Mode}}' myservice\n# => {\"Global\":{}}  -> recreate as replicated, or scale by nodes","handlingStrategy":"validation","validationCode":"if flags.Changed(flagReplicas) {\n\tres, err := apiClient.ServiceInspect(ctx, id, client.ServiceInspectOptions{})\n\tif err != nil { return err }\n\tif res.Service.Spec.Mode.Replicated == nil {\n\t\treturn fmt.Errorf(\"service %s is not replicated; --replicas unsupported\", id)\n\t}\n}","typeGuard":"func isReplicatedMode(m *swarm.ServiceMode) bool {\n\treturn m != nil && m.Replicated != nil\n}","tryCatchPattern":null,"preventionTips":["Check Spec.Mode.Replicated before passing --replicas.","Keep mode and replica-count decisions in the same place (service creation).","Document global services as node-scaled in runbooks."],"tags":["docker","swarm","service","replicas","replicated-mode"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}