use_api_socket can't be used with a Windows Docker Engine

Error message

use_api_socket can't be used with a Windows Docker Engine

What it means

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.

Source

Thrown at pkg/compose/apiSocket.go:45

// --use-api-socket is not actually supported by the Docker Engine
// but is a client-side hack (see https://github.com/docker/cli/blob/master/cli/command/container/create.go#L246)
// we replicate here by transforming the project model

func (s *composeService) useAPISocket(project *types.Project) (*types.Project, error) {
	useAPISocket := false
	for _, service := range project.Services {
		if service.UseAPISocket {
			useAPISocket = true
			break
		}
	}
	if !useAPISocket {
		return project, nil
	}

	if s.getContextInfo().ServerOSType() == "windows" {
		return nil, errors.New("use_api_socket can't be used with a Windows Docker Engine")
	}

	creds, err := s.configFile().GetAllCredentials()
	if err != nil {
		return nil, fmt.Errorf("resolving credentials failed: %w", err)
	}

	newConfig := &configfile.ConfigFile{
		AuthConfigs: creds,
	}
	var configBuf bytes.Buffer
	if err := newConfig.SaveToWriter(&configBuf); err != nil {
		return nil, fmt.Errorf("saving creds for API socket: %w", err)
	}

	project.Configs["#apisocket"] = types.ConfigObjConfig{
		Content: configBuf.String(),
	}

View on GitHub (pinned to ddc4b044b6)

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.

Example fix

# before (compose.yaml)
services:
  agent:
    image: my-agent
    use_api_socket: true

# after (profile-gated, only enabled with --profile agent on linux engines)
services:
  agent:
    image: my-agent
    use_api_socket: true
    profiles: ["linux-socket"]

Defensive patterns

Strategy: validation

Validate before calling

# refuse to run socket-injecting services against a Windows engine
if docker context inspect --format '{{.Endpoints.docker.Host}}' 2>/dev/null | grep -qi 'windows'; then
  echo "use_api_socket unsupported on Windows engines" >&2
  exit 1
fi
docker compose up

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of docker/compose@ddc4b044b6 (2026-08-15). Data as JSON: /api/errors/b3996cfa2b21d40b. Report an issue: GitHub.