docker/cli · error

replicas can only be used with replicated mode

Error message

replicas can only be used with replicated mode

What it means

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.

Source

Thrown at cli/command/service/update.go:1138

func equalProtocol(prot1, prot2 network.IPProtocol) bool {
	return prot1 == prot2 ||
		(prot1 == "" && prot2 == network.TCP) ||
		(prot2 == "" && prot1 == network.TCP)
}

func equalPublishMode(mode1, mode2 swarm.PortConfigPublishMode) bool {
	return mode1 == mode2 ||
		(mode1 == "" && mode2 == swarm.PortConfigPublishModeIngress) ||
		(mode2 == "" && mode1 == swarm.PortConfigPublishModeIngress)
}

func updateReplicas(flags *pflag.FlagSet, serviceMode *swarm.ServiceMode) error {
	if !flags.Changed(flagReplicas) {
		return nil
	}

	if serviceMode == nil || serviceMode.Replicated == nil {
		return errors.New("replicas can only be used with replicated mode")
	}
	serviceMode.Replicated.Replicas = flags.Lookup(flagReplicas).Value.(*Uint64Opt).Value()
	return nil
}

type hostMapping struct {
	IPAddr string
	Host   string
}

// updateHosts performs a diff between existing host entries, entries to be
// removed, and entries to be added. Host entries preserve the order in which they
// were added, as the specification mentions that in case multiple entries for a
// host exist, the first entry should be used (by default).
//
// Note that, even though unsupported by the CLI, the service specs format
// allow entries with both a _canonical_ hostname, and one or more aliases
// in an entry (IP-address canonical_hostname [alias ...])

View on GitHub (pinned to e9452d6e78)

Solutions

1. Verify the mode: `docker service inspect --format '{{json .Spec.Mode}}' <svc>`; for global services replica count is one-per-node by design
2. For replicated-job services use `docker service scale <svc>=N` (which sets TotalCompletions) instead of --replicas
3. If replicated behavior is wanted, recreate the service with `--mode replicated` — mode cannot be changed via update

Example fix

# before
docker service update --replicas 5 global-agent   # fails

# after (service recreated as replicated)
docker service create --mode replicated --replicas 5 --name agent myimg

When it happens

Trigger: `docker service update --replicas N <svc>` on a service whose mode is global, global-job, or replicated-job (serviceMode.Replicated == nil at update time).

Common situations: 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.

Related errors

• scale can only be used with replicated or replicated-job mod
• other flags may not be combined with --rollback
• duplicate mount target
• replicas can only be used with replicated or replicated-job
• unrecognized service mode

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