{"record":{"id":"b3996cfa2b21d40b","repo":"docker/compose","slug":"use-api-socket-can-t-be-used-with-a-windows-docker","errorCode":null,"errorMessage":"use_api_socket can't be used with a Windows Docker Engine","messagePattern":"use_api_socket can't be used with a Windows Docker Engine","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/compose/apiSocket.go","lineNumber":45,"sourceCode":"\n// --use-api-socket is not actually supported by the Docker Engine\n// but is a client-side hack (see https://github.com/docker/cli/blob/master/cli/command/container/create.go#L246)\n// we replicate here by transforming the project model\n\nfunc (s *composeService) useAPISocket(project *types.Project) (*types.Project, error) {\n\tuseAPISocket := false\n\tfor _, service := range project.Services {\n\t\tif service.UseAPISocket {\n\t\t\tuseAPISocket = true\n\t\t\tbreak\n\t\t}\n\t}\n\tif !useAPISocket {\n\t\treturn project, nil\n\t}\n\n\tif s.getContextInfo().ServerOSType() == \"windows\" {\n\t\treturn nil, errors.New(\"use_api_socket can't be used with a Windows Docker Engine\")\n\t}\n\n\tcreds, err := s.configFile().GetAllCredentials()\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"resolving credentials failed: %w\", err)\n\t}\n\n\tnewConfig := &configfile.ConfigFile{\n\t\tAuthConfigs: creds,\n\t}\n\tvar configBuf bytes.Buffer\n\tif err := newConfig.SaveToWriter(&configBuf); err != nil {\n\t\treturn nil, fmt.Errorf(\"saving creds for API socket: %w\", err)\n\t}\n\n\tproject.Configs[\"#apisocket\"] = types.ConfigObjConfig{\n\t\tContent: configBuf.String(),\n\t}","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/docker/compose/blob/ddc4b044b62e9f715212ea4143fa830fac76382f/pkg/compose/apiSocket.go#L27-L63","documentation":"A service configured with use_api_socket: true injects the Docker API socket (and a synthesized config with credentials) into that service's containers so it can drive the engine. This mechanism relies on Unix-domain socket bind-mounts, which a Windows Docker Engine cannot provide; in pkg/compose/apiSocket.go the project is scanned for any service with UseAPISocket and, if the context's ServerOSType() is \"windows\", project conversion fails with this error.","triggerScenarios":"A compose file with `services: dind: { use_api_socket: true }` (or any service setting it) run against a Docker context whose engine runs Windows containers; also hitting it when a Windows container target is selected by profile.","commonSituations":"Cross-platform teams reusing a Linux-oriented compose stack (with an agent service using the API socket) on Windows container mode; switching docker context to a Windows engine while keeping the same file.","solutions":["Switch the Docker context back to a Linux engine (docker context use <linux-context>) if the workload is Linux-based.","Remove or disable use_api_socket: true for the offending service when targeting Windows engines.","Gate the service behind a profile that is only activated on Linux and omit it for Windows runs."],"exampleFix":"# before (compose.yaml)\nservices:\n  agent:\n    image: my-agent\n    use_api_socket: true\n\n# after (profile-gated, only enabled with --profile agent on linux engines)\nservices:\n  agent:\n    image: my-agent\n    use_api_socket: true\n    profiles: [\"linux-socket\"]","handlingStrategy":"validation","validationCode":"# refuse to run socket-injecting services against a Windows engine\nif docker context inspect --format '{{.Endpoints.docker.Host}}' 2>/dev/null | grep -qi 'windows'; then\n  echo \"use_api_socket unsupported on Windows engines\" >&2\n  exit 1\nfi\ndocker compose up","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Profile-gate services that need use_api_socket so they activate only on Linux engines.","Pin the docker context explicitly in scripts (docker context use) to avoid accidental Windows engines."],"tags":["windows","api-socket","engine","compose-file"],"backgroundTag":null,"analyzedSha":"ddc4b044b62e9f715212ea4143fa830fac76382f","analyzedAt":"2026-08-15T13:31:42.319Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}