scale can only be used with replicated or replicated-job mod

Error message

scale can only be used with replicated or replicated-job mode

What it means

Emitted by `docker service scale`. runServiceScale (scale.go:95-109) inspects the service and only knows how to set Replicated.Replicas or ReplicatedJob.TotalCompletions; if the service's mode is global or global-job (the default branch of the switch), scaling is meaningless because those modes run exactly one task per matching node, so the CLI refuses.

Source

Thrown at cli/command/service/scale.go:108

		}
	}
	return errors.Join(errs...)
}

func runServiceScale(ctx context.Context, apiClient client.ServiceAPIClient, serviceID string, scale uint64) (warnings []string, _ error) {
	res, err := apiClient.ServiceInspect(ctx, serviceID, client.ServiceInspectOptions{})
	if err != nil {
		return nil, err
	}

	serviceMode := &res.Service.Spec.Mode
	switch {
	case serviceMode.Replicated != nil:
		serviceMode.Replicated.Replicas = &scale
	case serviceMode.ReplicatedJob != nil:
		serviceMode.ReplicatedJob.TotalCompletions = &scale
	default:
		return nil, errors.New("scale can only be used with replicated or replicated-job mode")
	}

	response, err := apiClient.ServiceUpdate(ctx, res.Service.ID, client.ServiceUpdateOptions{
		Version: res.Service.Version,
		Spec:    res.Service.Spec,
	})
	if err != nil {
		return nil, err
	}
	return response.Warnings, nil
}

// completeScaleArgs returns a completion function for the args of the scale command.
// It completes service names followed by "=", suppressing the trailing space.
func completeScaleArgs(dockerCli command.Cli) func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
	return func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
		// reuse the existing logic for configurable completion of service names and IDs.
		completions, directive := completeServiceNames(dockerCli)(cmd, args, toComplete)

View on GitHub (pinned to e9452d6e78)

Solutions

Check the mode with `docker service inspect --format '{{json .Spec.Mode}}' <svc>`; if global, scaling is per-node by design — add/remove nodes or use placement constraints instead
If the service should be replicated, recreate it: `docker service rm <svc>` then `docker service create --mode replicated --replicas N ...` (mode cannot be changed on update)
For jobs, use `--mode replicated-job` so TotalCompletions can be scaled

Example fix

# before
docker service create --mode global --name agent myimg
docker service scale agent=3   # fails

# after
docker service create --mode replicated --replicas 1 --name agent myimg
docker service scale agent=3

When it happens

Trigger: `docker service scale <svc>=N` against a service created with `--mode global` or `--mode global-job`; the ServiceInspect result has neither Spec.Mode.Replicated nor Spec.Mode.ReplicatedJob set.

Common situations: Trying to scale monitoring/logging agents (node-exporter, fluentd) that are intentionally deployed global; compose stacks with `deploy.mode: global`; confusing global mode (one task per node) with replicated mode.

Related errors

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/b51de2da9f218a47.json. Report an issue: GitHub.