replicas can only be used with replicated or replicated-job…

Error message

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

What it means

In `serviceOptions.ToServiceMode()` at opts.go:625-631, the `--mode global` case checks whether `--replicas` was also set. Global services run exactly one task per node, so a replica count is semantically meaningless. This error fires when `options.replicas.Value() != nil` inside the `case "global"` branch (line 629-630).

Solutions

Remove the `--replicas` flag when using `--mode global`
Switch to `--mode replicated` if you need to specify a replica count
Use `--mode replicated-job` if you need replicas in a job context

Example fix

# before
docker service create --mode global --replicas 3 --image nginx web
# error: replicas can only be used with replicated or replicated-job mode

# after (global: one task per node)
docker service create --mode global --image nginx web

# after (replicated: N tasks)
docker service create --mode replicated --replicas 3 --image nginx web

Defensive patterns

Strategy: validation

Validate before calling

// Validate mode/flag compatibility before calling ToServiceMode
func validateReplicasWithMode(mode string, replicas *uint64) error {
    if mode == "global" || mode == "global-job" {
        if replicas != nil {
            return errors.New("replicas can only be used with replicated or replicated-job mode")
        }
    }
    return nil
}

Prevention

Global and global-job modes do not accept --replicas — remove it from templates when switching modes
Build mode-specific flag sets in deployment scripts rather than applying all flags unconditionally
Document the valid flag combinations per service mode in your team's runbook

When it happens

Trigger: Running `docker service create --mode global --replicas 3 --image nginx web`. The `--replicas` flag populates `options.replicas` (a `Uint64Opt`); when mode is "global", any non-nil replica value triggers this error.

Common situations: A developer copies a `docker service create` command from a replicated template and switches `--mode` to `global` but forgets to remove `--replicas`. Or a script conditionally sets both flags.

Related errors

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/fe1798b0af655a23. Report an issue: GitHub.

Appendix: source

Thrown at cli/command/service/opts.go:630

		groups:          opts.NewListOpts(nil),
		logDriver:       newLogDriverOptions(),
		dns:             opts.NewListOpts(opts.ValidateIPAddress),
		dnsOption:       opts.NewListOpts(nil),
		dnsSearch:       opts.NewListOpts(opts.ValidateDNSSearch),
		hosts:           opts.NewListOpts(opts.ValidateExtraHost),
		sysctls:         opts.NewListOpts(nil),
		capAdd:          opts.NewListOpts(nil),
		capDrop:         opts.NewListOpts(nil),
		ulimits:         *opts.NewUlimitOpt(nil),
	}
}

func (options *serviceOptions) ToServiceMode() (swarm.ServiceMode, error) {
	serviceMode := swarm.ServiceMode{}
	switch options.mode {
	case "global":
		if options.replicas.Value() != nil {
			return serviceMode, errors.New("replicas can only be used with replicated or replicated-job mode")
		}

		if options.maxReplicas > 0 {
			return serviceMode, errors.New("replicas-max-per-node can only be used with replicated or replicated-job mode")
		}
		if options.maxConcurrent.Value() != nil {
			return serviceMode, errors.New("max-concurrent can only be used with replicated-job mode")
		}

		serviceMode.Global = &swarm.GlobalService{}
	case "replicated":
		if options.maxConcurrent.Value() != nil {
			return serviceMode, errors.New("max-concurrent can only be used with replicated-job mode")
		}

		serviceMode.Replicated = &swarm.ReplicatedService{
			Replicas: options.replicas.Value(),
		}

View on GitHub (pinned to 4f84911bfe)