"-- " is only supported on a Docker daemon with…

Error message

"--%s" is only supported on a Docker daemon with experimental features enabled

What it means

Thrown by areFlagsSupported() when a flag carrying the `experimental` annotation is set but details.ServerInfo().HasExperimental is false. The experimental capability is reported by the daemon during the ping; if the daemon was not started with experimental features enabled, this guard rejects the flag.

Solutions

Enable experimental features on the daemon: restart dockerd with --experimental, or set "experimental": true in /etc/docker/daemon.json and restart.
Remove the --<flag> if you do not need the experimental capability.
Upgrade the daemon/CLI — the flag may have become stable (annotation removed) in a newer version.

Example fix

# before: dockerd without experimental
docker <cmd> --<experimental-flag>
# after
# /etc/docker/daemon.json
{"experimental": true}
# then
sudo systemctl restart docker
docker <cmd> --<experimental-flag>

Defensive patterns

Strategy: validation

Validate before calling

info, err := cli.ServerInfo(ctx)
if err != nil { return err }
if !info.HasExperimental { /* do not pass experimental flag */ }

Prevention

Standardize daemon.json with "experimental": true if preview flags are used.
Gate experimental flags behind a config check in automation.
Upgrade so flags graduate out of experimental.

When it happens

Trigger: Passing an experimental-annotated flag (e.g. early-stage flags) against a daemon that was not launched with --experimental.

Common situations: Using a flag that graduated from experimental on an older daemon that still gates it behind experimental; daemon config without `"experimental": true` in daemon.json; pointing at a stock daemon while testing preview features.

Related errors

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

Appendix: source

Thrown at cmd/docker/docker.go:700

		// 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() {
		// 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 commands that do not require a
		// daemon connection).
		//
		// See commit b39739123b845f872549e91be184cc583f5b387c for details.

View on GitHub (pinned to 4f84911bfe)