{"id":"2144e91fe98ec219","repo":"docker/cli","slug":"flag-use-api-socket-can-t-be-used-with-a-windows","errorCode":null,"errorMessage":"flag --use-api-socket can't be used with a Windows Docker Engine","messagePattern":"flag --use-api-socket can't be used with a Windows Docker Engine","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/container/create.go","lineNumber":254,"sourceCode":"\tref, err := reference.ParseAnyReference(config.Image)\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\tif named, ok := ref.(reference.Named); ok {\n\t\tnamedRef = reference.TagNameOnly(named)\n\t}\n\n\tconst dockerConfigPathInContainer = \"/run/secrets/docker/config.json\"\n\tvar apiSocketCreds map[string]types.AuthConfig\n\n\tif options.useAPISocket {\n\t\t// We'll create two new mounts to handle this flag:\n\t\t//\n\t\t// 1. Mount the actual docker socket.\n\t\t// 2. A synthesized ~/.docker/config.json with resolved tokens.\n\n\t\tif dockerCLI.ServerInfo().OSType == \"windows\" {\n\t\t\treturn \"\", errors.New(\"flag --use-api-socket can't be used with a Windows Docker Engine\")\n\t\t}\n\n\t\t// hard-code engine socket path until https://github.com/moby/moby/pull/43459 gives us a discovery mechanism\n\t\tcontainerCfg.HostConfig.Mounts = append(containerCfg.HostConfig.Mounts, mount.Mount{\n\t\t\tType:        mount.TypeBind,\n\t\t\tSource:      \"/var/run/docker.sock\",\n\t\t\tTarget:      \"/var/run/docker.sock\",\n\t\t\tBindOptions: &mount.BindOptions{},\n\t\t})\n\n\t\t/*\n\n\t\t   Ideally, we'd like to copy the config into a tmpfs but unfortunately,\n\t\t   the mounts won't be in place until we start the container. This can\n\t\t   leave around the config if the container doesn't get deleted.\n\n\t\t   We are using the most compose-secret-compatible approach,\n\t\t   which is implemented at","sourceCodeStart":236,"sourceCodeEnd":272,"githubUrl":"https://github.com/docker/cli/blob/e9452d6e785f6e365712b9d71bd7517591773c86/cli/command/container/create.go#L236-L272","documentation":"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.","triggerScenarios":"`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.","commonSituations":"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.","solutions":["Switch to a Linux engine (Docker Desktop: 'Switch to Linux containers…') or select a Linux docker context, then retry.","Drop --use-api-socket and, on Windows, mount the named pipe manually if daemon access is needed: `-v \\\\.\\pipe\\docker_engine:\\\\.\\pipe\\docker_engine`.","Verify which engine you're talking to with `docker version` / `docker info --format '{{.OSType}}'`."],"exampleFix":"# before (Windows engine)\ndocker run --use-api-socket myimage\n# after (switch context to a Linux engine first)\ndocker context use desktop-linux\ndocker run --use-api-socket myimage","handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":["docker-cli","windows","docker-socket","platform-compatibility"],"analyzedSha":"e9452d6e785f6e365712b9d71bd7517591773c86","analyzedAt":"2026-08-01T07:09:22.474Z","schemaVersion":2}