"-- " is only supported on a Docker daemon running on , but…

Error message

"--%s" is only supported on a Docker daemon running on %s, but the Docker daemon is running on %s

What it means

Thrown by areFlagsSupported() when a CLI flag carrying the `ostype` annotation is set (f.Changed) but the connected daemon's reported OStype does not match the required value. The daemon's OStype is fetched lazily from ServerInfo() (a /v2.32.0 ping to the daemon). It tells the user the flag is platform-specific (e.g. a Windows-only flag) and the daemon is on a different platform.

Solutions

Remove the unsupported --<flag> from your command (it is annotated for a different OStype).
Connect the CLI to a daemon running on the required OS (set DOCKER_HOST to the matching node).
Check `docker version` / `docker info` to confirm Server OSType before scripting.

Example fix

# before (Windows daemon)
docker run --<linux-only-flag> ...
# after: drop the flag or target a linux daemon
docker run ...
# or
DOCKER_HOST=tcp://linux-node:2375 docker run --<linux-only-flag> ...

Defensive patterns

Strategy: validation

Validate before calling

// before invoking, confirm the daemon OS matches the flag's requirement
info, err := cli.ServerInfo(ctx)
if err != nil { return err }
if info.OSType != "linux" { /* skip the linux-only flag */ }

Prevention

Run `docker info` and read OSType before scripting platform-specific flags.
Pin DOCKER_HOST / use a known docker context for the required platform.
Avoid annotating your own commands with ostype unless the daemon matches.

When it happens

Trigger: Running a docker command with a flag annotated ostype!=daemon-OSType (e.g. a flag requiring 'linux' on a Windows daemon) while that flag is explicitly passed on the command line.

Common situations: Pointing the CLI at a Windows Docker daemon while using Linux-only flags, or vice-versa; mixing Docker Desktop (linuxkit) flags against a native Windows/Mac daemon; scripting against a remote daemon whose OStype differs from the local assumption.

Related errors

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

Appendix: source

Thrown at cmd/docker/docker.go:692

	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...)
}

// Check recursively so that, e.g., `docker stack ls` returns the same output as `docker stack`
func areSubcommandsSupported(cmd *cobra.Command, details versionDetails) error {
	// Check recursively so that, e.g., `docker stack ls` returns the same output as `docker stack`
	for curr := cmd; curr != nil; curr = curr.Parent() {

View on GitHub (pinned to 4f84911bfe)