{"record":{"id":"5627b3e3c2d76792","repo":"docker/cli","slug":"unrecognized-service-mode","errorCode":null,"errorMessage":"unrecognized service mode","messagePattern":"unrecognized service mode","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/service/progress/progress.go","lineNumber":253,"sourceCode":"\tif service.Spec.Mode.Replicated != nil && service.Spec.Mode.Replicated.Replicas != nil {\n\t\treturn &replicatedProgressUpdater{\n\t\t\tprogressOut: progressOut,\n\t\t}, nil\n\t}\n\tif service.Spec.Mode.Global != nil {\n\t\treturn &globalProgressUpdater{\n\t\t\tprogressOut: progressOut,\n\t\t}, nil\n\t}\n\tif service.Spec.Mode.ReplicatedJob != nil {\n\t\treturn newReplicatedJobProgressUpdater(service, progressOut), nil\n\t}\n\tif service.Spec.Mode.GlobalJob != nil {\n\t\treturn &globalJobProgressUpdater{\n\t\t\tprogressOut: progressOut,\n\t\t}, nil\n\t}\n\treturn nil, errors.New(\"unrecognized service mode\")\n}\n\nfunc writeOverallProgress(progressOut progress.Output, numerator, denominator int, rollback bool) {\n\tif rollback {\n\t\tprogressOut.WriteProgress(progress.Progress{\n\t\t\tID:     \"overall progress\",\n\t\t\tAction: fmt.Sprintf(\"rolling back update: %d out of %d tasks\", numerator, denominator),\n\t\t})\n\t\treturn\n\t}\n\tprogressOut.WriteProgress(progress.Progress{\n\t\tID:     \"overall progress\",\n\t\tAction: fmt.Sprintf(\"%d out of %d tasks\", numerator, denominator),\n\t})\n}\n\nfunc truncError(errMsg string) string {\n\t// Remove newlines from the error, which corrupt the output.","sourceCodeStart":235,"sourceCodeEnd":271,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/service/progress/progress.go#L235-L271","documentation":"In `progress.initializeUpdater()` (progress.go:234-253), the function inspects the service's `Spec.Mode` field to select the appropriate progress updater (replicated, global, replicated-job, or global-job). If none of the four mode sub-structs (`Replicated`, `Global`, `ReplicatedJob`, `GlobalJob`) is non-nil, the function falls through to line 253 and returns this error. Under normal operation, a Docker Swarm service always has exactly one mode set. This error indicates a corrupt or unexpected service spec — possibly from a newer engine API with an unrecognized mode, or data corruption.","triggerScenarios":"Calling `ServiceProgress()` on a service whose `Spec.Mode` has all four sub-structs nil. This is an internal invariant violation — it should not happen with services created by the standard Docker API. Could theoretically occur if the swarm store is corrupted, or if a future API version introduces a new mode that this CLI version does not recognize.","commonSituations":"Version skew: an older CLI connected to a newer Docker Engine that supports a service mode the CLI does not know about. Or a manually constructed/corrupted swarm service object passed to the progress API.","solutions":["Verify the service mode using `docker service inspect --format '{{.Spec.Mode}}' <service>` — if the mode is empty or unrecognized, the service spec is corrupt","Upgrade the Docker CLI to match or exceed the Docker Engine version","Recreate the service with a known mode (`--mode replicated`, `global`, `replicated-job`, or `global-job`)"],"exampleFix":"# diagnose the service mode\ndocker service inspect --format '{{json .Spec.Mode}}' myservice\n\n# if mode is empty/corrupt, recreate the service\ndocker service rm myservice\ndocker service create --name myservice --mode replicated --replicas 3 --image nginx","handlingStrategy":"try-catch","validationCode":"// Before calling ServiceProgress, verify the service mode is recognized\nfunc isRecognizedMode(mode swarm.ServiceMode) bool {\n    return mode.Replicated != nil || mode.Global != nil ||\n        mode.ReplicatedJob != nil || mode.GlobalJob != nil\n}\n\n// Usage:\n// res, _ := apiClient.ServiceInspect(ctx, svcID, opts)\n// if !isRecognizedMode(res.Service.Spec.Mode) {\n//     return errors.New(\"service has no recognized mode\")\n// }","typeGuard":"// Type guard for swarm.ServiceMode\ndefunc hasKnownServiceMode(m swarm.ServiceMode) bool {\n    return m.Replicated != nil || m.Global != nil ||\n        m.ReplicatedJob != nil || m.GlobalJob != nil\n}","tryCatchPattern":"// Wrap ServiceProgress in error handling\nerr := progress.ServiceProgress(ctx, apiClient, svcID, progressWriter)\nif err != nil && strings.Contains(err.Error(), \"unrecognized service mode\") {\n    // Service spec is corrupt or CLI version is too old for this mode\n    log.Printf(\"service %s has an unrecognized mode; inspect manually: %v\", svcID, err)\n    // Fall back to non-blocking monitoring\n    return nil\n}","preventionTips":["Ensure the Docker CLI version matches or exceeds the Docker Engine version","Validate the service mode before calling ServiceProgress","Recreate corrupt services with a known, standard mode"],"tags":["docker","cli","service","swarm","progress","internal-invariant"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}