{"record":{"id":"12b6c4de883f51fa","repo":"docker/cli","slug":"s-requires-api-version-s-but-the-docker-daemon","errorCode":null,"errorMessage":"%s requires API version %s, but the Docker daemon API version is %s","messagePattern":"(.+?) requires API version (.+?), but the Docker daemon API version is (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/docker/docker.go","lineNumber":720,"sourceCode":"\t\t// buildkit-specific flags are noop when buildkit is not enabled, so we do not add an error in that case\n\t})\n\treturn errors.Join(errs...)\n}\n\n// Check recursively so that, e.g., `docker stack ls` returns the same output as `docker stack`\nfunc areSubcommandsSupported(cmd *cobra.Command, details versionDetails) error {\n\t// Check recursively so that, e.g., `docker stack ls` returns the same output as `docker stack`\n\tfor curr := cmd; curr != nil; curr = curr.Parent() {\n\t\t// Important: in the code below, calls to \"details.CurrentVersion()\" and\n\t\t// \"details.ServerInfo()\" are deliberately executed inline to make them\n\t\t// be executed \"lazily\". This is to prevent making a connection with the\n\t\t// daemon to perform a \"ping\" (even for commands that do not require a\n\t\t// daemon connection).\n\t\t//\n\t\t// See commit b39739123b845f872549e91be184cc583f5b387c for details.\n\n\t\tif cmdVersion, ok := curr.Annotations[\"version\"]; ok && versions.LessThan(details.CurrentVersion(), cmdVersion) {\n\t\t\treturn fmt.Errorf(\"%s requires API version %s, but the Docker daemon API version is %s\", cmd.CommandPath(), cmdVersion, details.CurrentVersion())\n\t\t}\n\t\tif ost, ok := curr.Annotations[\"ostype\"]; ok && details.ServerInfo().OSType != \"\" && ost != details.ServerInfo().OSType {\n\t\t\treturn fmt.Errorf(\"%s is only supported on a Docker daemon running on %s, but the Docker daemon is running on %s\", cmd.CommandPath(), ost, details.ServerInfo().OSType)\n\t\t}\n\t\tif _, ok := curr.Annotations[\"experimental\"]; ok && !details.ServerInfo().HasExperimental {\n\t\t\treturn fmt.Errorf(\"%s is only supported on a Docker daemon with experimental features enabled\", cmd.CommandPath())\n\t\t}\n\t}\n\treturn nil\n}\n\nfunc getFlagAnnotation(f *pflag.Flag, annotation string) string {\n\tif value, ok := f.Annotations[annotation]; ok && len(value) == 1 {\n\t\treturn value[0]\n\t}\n\treturn \"\"\n}\n","sourceCodeStart":702,"sourceCodeEnd":738,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cmd/docker/docker.go#L702-L738","documentation":"Thrown by areSubcommandsSupported() when the command (or any parent, walked up the cobra tree) has a `version` annotation whose required API version is greater than the daemon's actual API version (compared via versions.LessThan). It means the daemon is too old to support this subcommand.","triggerScenarios":"Invoking a subcommand annotated with a minimum API version (e.g. `docker checkpoint`, `docker buildx`) against a daemon whose reported API version is lower than required.","commonSituations":"New CLI talking to an older daemon (version skew); pinned old dockerd on servers; remote DOCKER_HOST pointing at a stale node; downgrading the daemon but keeping a newer CLI.","solutions":["Upgrade the Docker daemon on the target host so its API version >= the required version.","Install an older CLI matching the daemon's API version (set DOCKER_API_VERSION to match and use a compatible CLI).","Point DOCKER_HOST at a daemon that already meets the version requirement."],"exampleFix":"# before\n# daemon API 1.30, command requires 1.40\ndocker checkpoint ls\n# after: upgrade dockerd, verify\nsudo apt-get install --only-upgrade docker-ce\ndocker version  # Server Version >= required\nDOCKER_API_VERSION=1.40 docker checkpoint ls","handlingStrategy":"validation","validationCode":"// ensure CLI/daemon API compatibility before running\nv, err := cli.ServerAPIVersion(ctx)\nif err != nil { return err }\nrequired, _ := versions.NewVersion(\"1.40\")\nactual, _ := versions.NewVersion(v)\nif actual.LessThan(required) { return fmt.Errorf(\"daemon API %s too old\", v) }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep daemon and CLI versions aligned.","Set DOCKER_API_VERSION explicitly to match the daemon for scripts.","Check `docker version` Server API version in CI before using new commands."],"tags":["docker","cli","daemon","api-version","version-skew"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}