{"record":{"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/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/container/create.go#L236-L272","documentation":"Returned when the experimental --use-api-socket flag is combined with a Docker Engine whose OSType is \"windows\" (create.go:253-255). The flag bind-mounts /var/run/docker.sock and injects credentials via a Linux path scheme, neither of which exists on a Windows engine. The check fires before any container-creation side effects.","triggerScenarios":"Running `docker run --use-api-socket <img>` or `docker create --use-api-socket <img>` while the connected daemon reports ServerInfo().OSType == \"windows\" (e.g. Docker Desktop on Windows targeting a Windows container engine, or DOCKER_HOST pointing at a Windows daemon).","commonSituations":"Switching Docker Desktop between Linux and Windows container modes and forgetting --use-api-socket is Linux-only; CI pipelines that set DOCKER_HOST to a remote Windows engine; scripts copied from a Linux dev box to a Windows host.","solutions":["Remove the --use-api-socket flag when targeting a Windows engine.","Switch Docker Desktop / the daemon to Linux containers (Linux engine) before using --use-api-socket.","If you need Docker API access inside a Windows container, manually bind the Windows named pipe (//./pipe/docker_engine) instead."],"exampleFix":"// before\ndocker run --use-api-socket myimage\n// after (on a Windows engine)\ndocker run myimage","handlingStrategy":"validation","validationCode":"// Before calling create/run with --use-api-socket, check the engine OS.\ninfo, err := cli.Client().ServerInfo(ctx)\nif err != nil { return err }\nif opts.useAPISocket && info.OSType == \"windows\" {\n    return errors.New(\"--use-api-socket requires a Linux engine\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Gate --use-api-socket behind a check of ServerInfo().OSType in wrapper scripts.","Document that the flag is experimental and Linux-only.","In CI, assert DOCKER_HOST targets a Linux engine before enabling the flag."],"tags":["docker-cli","windows","api-socket","experimental","container-create"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}