{"record":{"id":"b51de2da9f218a47","repo":"docker/cli","slug":"scale-can-only-be-used-with-replicated-or-replicat","errorCode":null,"errorMessage":"scale can only be used with replicated or replicated-job mode","messagePattern":"scale can only be used with replicated or replicated-job mode","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/service/scale.go","lineNumber":108,"sourceCode":"\t\t}\n\t}\n\treturn errors.Join(errs...)\n}\n\nfunc runServiceScale(ctx context.Context, apiClient client.ServiceAPIClient, serviceID string, scale uint64) (warnings []string, _ error) {\n\tres, err := apiClient.ServiceInspect(ctx, serviceID, client.ServiceInspectOptions{})\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tserviceMode := &res.Service.Spec.Mode\n\tswitch {\n\tcase serviceMode.Replicated != nil:\n\t\tserviceMode.Replicated.Replicas = &scale\n\tcase serviceMode.ReplicatedJob != nil:\n\t\tserviceMode.ReplicatedJob.TotalCompletions = &scale\n\tdefault:\n\t\treturn nil, errors.New(\"scale can only be used with replicated or replicated-job mode\")\n\t}\n\n\tresponse, err := apiClient.ServiceUpdate(ctx, res.Service.ID, client.ServiceUpdateOptions{\n\t\tVersion: res.Service.Version,\n\t\tSpec:    res.Service.Spec,\n\t})\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\treturn response.Warnings, nil\n}\n\n// completeScaleArgs returns a completion function for the args of the scale command.\n// It completes service names followed by \"=\", suppressing the trailing space.\nfunc completeScaleArgs(dockerCli command.Cli) func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {\n\treturn func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {\n\t\t// reuse the existing logic for configurable completion of service names and IDs.\n\t\tcompletions, directive := completeServiceNames(dockerCli)(cmd, args, toComplete)","sourceCodeStart":90,"sourceCodeEnd":126,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/service/scale.go#L90-L126","documentation":"Thrown by runServiceScale (cli/command/service/scale.go:108) when the inspected service's Spec.Mode is neither Replicated nor ReplicatedJob. Scaling works by writing to Replicated.Replicas or ReplicatedJob.TotalCompletions; global and global-job modes have no count field to mutate, so the switch statement falls through to its default branch.","triggerScenarios":"Running `docker service scale <svc>=N` against a service created with `--mode global` or `--mode global-job`. The ServiceInspect call succeeds, but neither case in the switch matches, hitting the default that returns this error.","commonSituations":"Operator forgets a service was deployed globally and scripts a scale call; a Compose file sets `deploy.mode: global` but the pipeline assumes it can scale; migrating a service between modes without recreating it.","solutions":["Recreate the service in a scalable mode if a fixed count is required: `docker service create --mode replicated --replicas N ...`.","For global services, scale horizontally by adding/removing swarm nodes rather than using `docker service scale`.","Inspect the mode before scaling: `docker service inspect --format '{{json .Spec.Mode}}' <svc>` and skip scale for non-replicated modes."],"exampleFix":"// before\ndocker service scale myservice=5   # myservice is --mode global\n\n// after\ndocker service inspect --format '{{json .Spec.Mode}}' myservice\n# => {\"Global\":{}}  -> do not scale; scale by adding nodes instead","handlingStrategy":"validation","validationCode":"// Before scaling, confirm the service is in a scalable mode.\nres, err := apiClient.ServiceInspect(ctx, id, client.ServiceInspectOptions{})\nif err != nil { return err }\nm := res.Service.Spec.Mode\nif m.Replicated == nil && m.ReplicatedJob == nil {\n    return fmt.Errorf(\"service %s is not replicated/replicated-job; cannot scale\", id)\n}\n// safe to scale now","typeGuard":"// Narrows a swarm.ServiceMode to a scalable count field.\nfunc scalableCount(m *swarm.ServiceMode) (set func(uint64), ok bool) {\n\tif m.Replicated != nil {\n\t\treturn func(n uint64) { m.Replicated.Replicas = &n }, true\n\t}\n\tif m.ReplicatedJob != nil {\n\t\treturn func(n uint64) { m.ReplicatedJob.TotalCompletions = &n }, true\n\t}\n\treturn nil, false\n}","tryCatchPattern":null,"preventionTips":["Always inspect Spec.Mode before scripting a scale call.","Reserve global mode for services that must run one-per-node.","Tag services with a label recording their intended scaling strategy."],"tags":["docker","swarm","service","scale","replicated-mode"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}