docker/cli · error

unrecognized service mode

Error message

unrecognized service mode

What it means

Returned by initializeUpdater in the service progress reporter when a service's Spec.Mode matches none of the four known variants (Replicated with non-nil Replicas, Global, ReplicatedJob, GlobalJob). The CLI cannot render deployment progress for a mode it doesn't recognize, so it fails fast instead of showing bogus progress.

Source

Thrown at cli/command/service/progress/progress.go:253

	if service.Spec.Mode.Replicated != nil && service.Spec.Mode.Replicated.Replicas != nil {
		return &replicatedProgressUpdater{
			progressOut: progressOut,
		}, nil
	}
	if service.Spec.Mode.Global != nil {
		return &globalProgressUpdater{
			progressOut: progressOut,
		}, nil
	}
	if service.Spec.Mode.ReplicatedJob != nil {
		return newReplicatedJobProgressUpdater(service, progressOut), nil
	}
	if service.Spec.Mode.GlobalJob != nil {
		return &globalJobProgressUpdater{
			progressOut: progressOut,
		}, nil
	}
	return nil, errors.New("unrecognized service mode")
}

func writeOverallProgress(progressOut progress.Output, numerator, denominator int, rollback bool) {
	if rollback {
		progressOut.WriteProgress(progress.Progress{
			ID:     "overall progress",
			Action: fmt.Sprintf("rolling back update: %d out of %d tasks", numerator, denominator),
		})
		return
	}
	progressOut.WriteProgress(progress.Progress{
		ID:     "overall progress",
		Action: fmt.Sprintf("%d out of %d tasks", numerator, denominator),
	})
}

func truncError(errMsg string) string {
	// Remove newlines from the error, which corrupt the output.

View on GitHub (pinned to e9452d6e78)

Solutions

1. Upgrade the Docker CLI so it recognizes the service's mode (check with `docker service inspect <svc> --format '{{json .Spec.Mode}}'`).
2. If a custom API client created the service, ensure exactly one of Replicated (with Replicas set), Global, ReplicatedJob, or GlobalJob is populated in ServiceMode.
3. As a workaround, run the command with --detach to skip progress monitoring.

Example fix

// before (custom API client)
spec.Mode = swarm.ServiceMode{}
// after
replicas := uint64(3)
spec.Mode = swarm.ServiceMode{Replicated: &swarm.ReplicatedService{Replicas: &replicas}}

When it happens

Trigger: docker service create/update with --detach=false (progress display) against a service whose inspected Mode struct has no recognized branch set — e.g. a newer daemon returning a mode this CLI version predates, a Replicated mode with a nil Replicas pointer from a nonstandard API client, or a hand-crafted service spec with an empty Mode.

Common situations: CLI/daemon version skew where the daemon supports a newer service mode; third-party tools creating services via the API with an incomplete ServiceMode; corrupted or mocked inspect responses in tests.

Related errors

• no replica count
• replicas can only be used with replicated or replicated-job
• node ID not found in /info
• replicas-max-per-node can only be used with replicated or re
• max-concurrent can only be used with replicated-job mode

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