docker/cli · error

flag --use-api-socket can't be used with a Windows Docker En

Error message

flag --use-api-socket can't be used with a Windows Docker Engine

What it means

In createContainer, the --use-api-socket flag bind-mounts the engine's Unix socket (/var/run/docker.sock) plus a synthesized ~/.docker/config.json into the new container. The CLI checks dockerCLI.ServerInfo().OSType and rejects the flag when the daemon is Windows, since Windows engines have no /var/run/docker.sock Unix socket to bind-mount.

Source

Thrown at cli/command/container/create.go:254

	ref, err := reference.ParseAnyReference(config.Image)
	if err != nil {
		return "", err
	}
	if named, ok := ref.(reference.Named); ok {
		namedRef = reference.TagNameOnly(named)
	}

	const dockerConfigPathInContainer = "/run/secrets/docker/config.json"
	var apiSocketCreds map[string]types.AuthConfig

	if options.useAPISocket {
		// We'll create two new mounts to handle this flag:
		//
		// 1. Mount the actual docker socket.
		// 2. A synthesized ~/.docker/config.json with resolved tokens.

		if dockerCLI.ServerInfo().OSType == "windows" {
			return "", errors.New("flag --use-api-socket can't be used with a Windows Docker Engine")
		}

		// hard-code engine socket path until https://github.com/moby/moby/pull/43459 gives us a discovery mechanism
		containerCfg.HostConfig.Mounts = append(containerCfg.HostConfig.Mounts, mount.Mount{
			Type:        mount.TypeBind,
			Source:      "/var/run/docker.sock",
			Target:      "/var/run/docker.sock",
			BindOptions: &mount.BindOptions{},
		})

		/*

		   Ideally, we'd like to copy the config into a tmpfs but unfortunately,
		   the mounts won't be in place until we start the container. This can
		   leave around the config if the container doesn't get deleted.

		   We are using the most compose-secret-compatible approach,
		   which is implemented at

View on GitHub (pinned to e9452d6e78)

Solutions

1. Switch to a Linux engine (Docker Desktop: 'Switch to Linux containers…') or select a Linux docker context, then retry.
2. Drop --use-api-socket and, on Windows, mount the named pipe manually if daemon access is needed: `-v \\.\pipe\docker_engine:\\.\pipe\docker_engine`.
3. Verify which engine you're talking to with `docker version` / `docker info --format '{{.OSType}}'`.

Example fix

# before (Windows engine)
docker run --use-api-socket myimage
# after (switch context to a Linux engine first)
docker context use desktop-linux
docker run --use-api-socket myimage

When it happens

Trigger: `docker run --use-api-socket ...` or `docker create --use-api-socket ...` against a daemon whose reported OSType is "windows" — i.e. Docker Desktop switched to Windows containers mode, or a remote Windows Docker Engine.

Common situations: Docker Desktop on Windows accidentally left in Windows-containers mode; CI targeting a Windows engine while reusing Linux-oriented scripts; DOCKER_HOST/context pointing at a Windows host.

Related errors

• error: cannot perform an interactive login from a non-TTY de
• invalid credential spec: value must be prefixed with "config
• failed to parse hook template
• unexpected hook response type:
• plugin candidate path cannot be empty

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/2144e91fe98ec219.json. Report an issue: GitHub.