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

Raised by convertDeployMode when a compose service declares `deploy.mode: global-job` while also setting `deploy.replicas`. A global-job runs exactly one task per matching node, so a replica count is contradictory; the converter rejects the combination instead of ignoring the replicas.

Source

Thrown at cli/compose/convert/service.go:637

	for name, value := range source {
		switch value {
		case nil:
			output = append(output, name)
		default:
			output = append(output, name+"="+*value)
		}
	}
	sort.Strings(output)
	return output
}

func convertDeployMode(mode string, replicas *uint64) (swarm.ServiceMode, error) {
	serviceMode := swarm.ServiceMode{}

	switch mode {
	case "global-job":
		if replicas != nil {
			return serviceMode, errors.New("replicas can only be used with replicated or replicated-job mode")
		}
		serviceMode.GlobalJob = &swarm.GlobalJob{}
	case "global":
		if replicas != nil {
			return serviceMode, errors.New("replicas can only be used with replicated or replicated-job mode")
		}
		serviceMode.Global = &swarm.GlobalService{}
	case "replicated-job":
		serviceMode.ReplicatedJob = &swarm.ReplicatedJob{
			MaxConcurrent:    replicas,
			TotalCompletions: replicas,
		}
	case "replicated", "":
		serviceMode.Replicated = &swarm.ReplicatedService{Replicas: replicas}
	default:
		return serviceMode, fmt.Errorf("unknown mode: %s", mode)
	}
	return serviceMode, nil

View on GitHub (pinned to e9452d6e78)

Solutions

Remove `replicas:` from the service's deploy block when using mode: global-job
If you want a fixed number of job tasks, use `mode: replicated-job` and keep replicas
Run `docker compose config` on merged files to locate the stray replicas key

Example fix

# before
deploy:
  mode: global-job
  replicas: 3
# after
deploy:
  mode: replicated-job
  replicas: 3

When it happens

Trigger: `docker stack deploy` of a compose file with `deploy: {mode: global-job, replicas: N}`. Any non-nil replicas pointer with mode 'global-job' triggers it during service conversion.

Common situations: Switching a service's mode from replicated-job to global-job and leaving `replicas:` behind; compose override files where a base file sets replicas and an override changes the mode; misunderstanding that global-job scales per-node, not by count.

Related errors

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