service %q build.platforms does not support value set by DOC

Error message

service %q build.platforms does not support value set by DOCKER_DEFAULT_PLATFORM: %s

What it means

During BuildOptions.Apply, the environment variable DOCKER_DEFAULT_PLATFORM is applied to every service with a build section. If the service declares an explicit build.platforms list and that list does not contain the requested platform, the build is aborted because the resulting image would not match the platform the user asked Docker to run. The message names the offending service and the platform value from the environment.

Source

Thrown at pkg/api/api.go:244

	SBOM string
	// Out is the stream to write build progress
	Out io.Writer
}

// Apply mutates project according to build options
func (o BuildOptions) Apply(project *types.Project) error {
	platform := project.Environment["DOCKER_DEFAULT_PLATFORM"]
	for name, service := range project.Services {
		if service.Provider == nil && service.Image == "" && service.Build == nil {
			return fmt.Errorf("invalid service %q. Must specify either image or build", name)
		}

		if service.Build == nil {
			continue
		}
		if platform != "" {
			if len(service.Build.Platforms) > 0 && !slices.Contains(service.Build.Platforms, platform) {
				return fmt.Errorf("service %q build.platforms does not support value set by DOCKER_DEFAULT_PLATFORM: %s", name, platform)
			}
			service.Platform = platform
		}
		if service.Platform != "" {
			if len(service.Build.Platforms) > 0 && !slices.Contains(service.Build.Platforms, service.Platform) {
				return fmt.Errorf("service %q build configuration does not support platform: %s", name, service.Platform)
			}
		}

		service.Build.Pull = service.Build.Pull || o.Pull
		service.Build.NoCache = service.Build.NoCache || o.NoCache

		project.Services[name] = service
	}
	return nil
}

// CreateOptions group options of the Create API

View on GitHub (pinned to ddc4b044b6)

Solutions

Unset or correct the variable for this build: DOCKER_DEFAULT_PLATFORM= docker compose build
Add the requested platform to the service's build.platforms list so it is a supported target
Remove the build.platforms restriction from the service if any platform is acceptable
Check .env and shell profiles for a stale DOCKER_DEFAULT_PLATFORM export

Example fix

# shell — before
export DOCKER_DEFAULT_PLATFORM=linux/arm64
# shell — after (option A: unset for this build)
unset DOCKER_DEFAULT_PLATFORM
# compose.yaml — after (option B: declare support)
services:
  web:
    build:
      platforms:
        - linux/amd64
        - linux/arm64

Defensive patterns

Strategy: validation

Validate before calling

// Before building, confirm the env platform is declared:
platform := os.Getenv("DOCKER_DEFAULT_PLATFORM")
for name, svc := range project.Services {
	if svc.Build == nil || platform == "" {
		continue
	}
	if len(svc.Build.Platforms) > 0 && !slices.Contains(svc.Build.Platforms, platform) {
		return fmt.Errorf("service %s: add %s to build.platforms or unset DOCKER_DEFAULT_PLATFORM", name, platform)
	}
}

Prevention

Keep DOCKER_DEFAULT_PLATFORM out of global shell profiles; scope it per-command
When pinning build.platforms, always include the host platform of every developer machine and CI runner
Use canonical platform strings (linux/arm64, not arm64) everywhere

When it happens

Trigger: DOCKER_DEFAULT_PLATFORM is set (e.g. linux/arm64) while a service's build.platforms lists only linux/amd64; or the env var holds a malformed value like 'arm64' instead of 'linux/arm64' that never string-matches an entry in platforms.

Common situations: Developers on Apple Silicon or Windows/ARM who set DOCKER_DEFAULT_PLATFORM globally for unrelated reasons, then build a compose project that pins platforms; CI pipelines that export DOCKER_DEFAULT_PLATFORM to emulate an architecture; a stale value left in a shell profile or .env file.

Related errors

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