docker/cli · error

"-- " requires API version , but the Docker daemon API…

Error message

"--%s" requires API version %s, but the Docker daemon API version is %s

What it means

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.

Solutions

1. Upgrade the Docker daemon to a version that exposes the required API version.
2. Remove the unsupported flag from your command.
3. Check `docker version` to compare Client and Server API versions.
4. If DOCKER_API_VERSION is explicitly pinned, unset it so the CLI negotiates the highest common version.

Example fix

// before
$ docker <cmd> --newflag
Error: "--newflag" requires API version 1.45, but the Docker daemon API version is 1.41

// after — drop the flag or upgrade the daemon
$ docker version   # confirm Server API version
# then either omit --newflag or upgrade Docker Engine on the daemon host

// Compare required flag API version against the daemon before using the flag
func daemonSupportsFlag(requiredAPI string) (bool, error) {
    out, err := exec.Command("docker", "version", "--format", "{{.Server.APIVersion}}").CombinedOutput()
    if err != nil { return false, err }
    daemon := strings.TrimSpace(string(out))
    return versions.GreaterThanOrEqualTo(daemon, requiredAPI), nil
}

// Gracefully drop the flag if the daemon is too old
if ok, _ := daemonSupportsFlag("1.45"); !ok {
    args = removeFlag(args, "--newflag")
}
_, err := exec.CommandContext(ctx, "docker", args...).CombinedOutput()

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• requires API version , but the Docker daemon API version is
• conflicting options: cannot specify both --password and…
• the --password-stdin option requires --username to be set
• username is empty
• password is empty

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/2b8f5de6b6d34dc1. Report an issue: GitHub.

Appendix: source

Thrown at cmd/docker/docker.go:688

}

func areFlagsSupported(cmd *cobra.Command, details versionDetails) error {
	var errs []error

	cmd.Flags().VisitAll(func(f *pflag.Flag) {
		if !f.Changed || len(f.Annotations) == 0 {
			return
		}
		// Important: in the code below, calls to "details.CurrentVersion()" and
		// "details.ServerInfo()" are deliberately executed inline to make them
		// be executed "lazily". This is to prevent making a connection with the
		// daemon to perform a "ping" (even for flags that do not require a
		// daemon connection).
		//
		// See commit b39739123b845f872549e91be184cc583f5b387c for details.

		if _, ok := f.Annotations["version"]; ok && !isVersionSupported(f, details.CurrentVersion()) {
			errs = append(errs, fmt.Errorf(`"--%s" requires API version %s, but the Docker daemon API version is %s`, f.Name, getFlagAnnotation(f, "version"), details.CurrentVersion()))
			return
		}
		if _, ok := f.Annotations["ostype"]; ok && !isOSTypeSupported(f, details.ServerInfo().OSType) {
			errs = append(errs, fmt.Errorf(
				`"--%s" is only supported on a Docker daemon running on %s, but the Docker daemon is running on %s`,
				f.Name,
				getFlagAnnotation(f, "ostype"), details.ServerInfo().OSType),
			)
			return
		}
		if _, ok := f.Annotations["experimental"]; ok && !details.ServerInfo().HasExperimental {
			errs = append(errs, fmt.Errorf(`"--%s" is only supported on a Docker daemon with experimental features enabled`, f.Name))
		}
		// buildkit-specific flags are noop when buildkit is not enabled, so we do not add an error in that case
	})
	return errors.Join(errs...)
}

View on GitHub (pinned to 4f84911bfe)