{"record":{"id":"2b8f5de6b6d34dc1","repo":"docker/cli","slug":"s-requires-api-version-s-but-the-docker-dae","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":688,"sourceCode":"}\n\nfunc areFlagsSupported(cmd *cobra.Command, details versionDetails) error {\n\tvar errs []error\n\n\tcmd.Flags().VisitAll(func(f *pflag.Flag) {\n\t\tif !f.Changed || len(f.Annotations) == 0 {\n\t\t\treturn\n\t\t}\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 flags 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 _, ok := f.Annotations[\"version\"]; ok && !isVersionSupported(f, details.CurrentVersion()) {\n\t\t\terrs = append(errs, fmt.Errorf(`\"--%s\" requires API version %s, but the Docker daemon API version is %s`, f.Name, getFlagAnnotation(f, \"version\"), details.CurrentVersion()))\n\t\t\treturn\n\t\t}\n\t\tif _, ok := f.Annotations[\"ostype\"]; ok && !isOSTypeSupported(f, details.ServerInfo().OSType) {\n\t\t\terrs = append(errs, fmt.Errorf(\n\t\t\t\t`\"--%s\" is only supported on a Docker daemon running on %s, but the Docker daemon is running on %s`,\n\t\t\t\tf.Name,\n\t\t\t\tgetFlagAnnotation(f, \"ostype\"), details.ServerInfo().OSType),\n\t\t\t)\n\t\t\treturn\n\t\t}\n\t\tif _, ok := f.Annotations[\"experimental\"]; ok && !details.ServerInfo().HasExperimental {\n\t\t\terrs = append(errs, fmt.Errorf(`\"--%s\" is only supported on a Docker daemon with experimental features enabled`, f.Name))\n\t\t}\n\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","sourceCodeStart":670,"sourceCodeEnd":706,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cmd/docker/docker.go#L670-L706","documentation":"Returned by areFlagsSupported() (called from the PersistentPreRunE isSupported check) when a flag the user passed is annotated with a minimum API \"version\" that exceeds the connected daemon's negotiated API version. %s is the flag name, second %s is the required version (from the flag annotation), third %s is details.CurrentVersion() — the daemon's actual API version obtained from the ping. The flag is therefore unavailable against this daemon.","triggerScenarios":"Running a docker command with a flag that requires a newer daemon than is connected — e.g. a flag introduced in API 1.45 against a daemon exposing 1.41. Happens with downgraded daemons, older Docker Engine, or when DOCKER_API_VERSION/DOCKER_HOST points at an older remote daemon.","commonSituations":"New CLI talking to an older Engine; remote daemon via DOCKER_HOST on an older host; DOCKER_API_VERSION pinned low; mixed-version Swarm nodes.","solutions":["Upgrade the Docker daemon to a version that exposes the required API version.","Remove the unsupported flag from your command.","Check `docker version` to compare Client and Server API versions.","If DOCKER_API_VERSION is explicitly pinned, unset it so the CLI negotiates the highest common version."],"exampleFix":"// before\n$ docker <cmd> --newflag\nError: \"--newflag\" requires API version 1.45, but the Docker daemon API version is 1.41\n\n// after — drop the flag or upgrade the daemon\n$ docker version   # confirm Server API version\n# then either omit --newflag or upgrade Docker Engine on the daemon host","handlingStrategy":"validation","validationCode":"// Compare required flag API version against the daemon before using the flag\nfunc daemonSupportsFlag(requiredAPI string) (bool, error) {\n    out, err := exec.Command(\"docker\", \"version\", \"--format\", \"{{.Server.APIVersion}}\").CombinedOutput()\n    if err != nil { return false, err }\n    daemon := strings.TrimSpace(string(out))\n    return versions.GreaterThanOrEqualTo(daemon, requiredAPI), nil\n}","typeGuard":null,"tryCatchPattern":"// Gracefully drop the flag if the daemon is too old\nif ok, _ := daemonSupportsFlag(\"1.45\"); !ok {\n    args = removeFlag(args, \"--newflag\")\n}\n_, err := exec.CommandContext(ctx, \"docker\", args...).CombinedOutput()","preventionTips":["Check `docker version` to align Client and Server API versions.","Avoid pinning DOCKER_API_VERSION below what your flags require.","Upgrade the daemon or drop unsupported flags in mixed-version environments."],"tags":["docker","api-version","compatibility","flags","daemon"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}