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

When DOCKER_DEFAULT_PLATFORM is set in the project environment and a service declares `platforms:` under its build section without also setting a top-level `platform:`, compose requires the env-var platform to be listed in build.platforms. If it is not, platform resolution fails because the image would be built/tagged for a platform the build config explicitly excludes.

Source

Thrown at cmd/compose/options.go:68

		if service.Build == nil || service.Platform != "" {
			continue
		}
		service.Platform = defaultPlatform
		project.Services[name] = service
	}
}

func applyPlatforms(project *types.Project, buildForSinglePlatform bool) error {
	defaultPlatform := project.Environment["DOCKER_DEFAULT_PLATFORM"]
	for name, service := range project.Services {
		if service.Build == nil {
			continue
		}

		// default platform only applies if the service doesn't specify
		if defaultPlatform != "" && service.Platform == "" {
			if len(service.Build.Platforms) > 0 && !slices.Contains(service.Build.Platforms, defaultPlatform) {
				return fmt.Errorf("service %q build.platforms does not support value set by DOCKER_DEFAULT_PLATFORM: %s", name, defaultPlatform)
			}
			service.Platform = defaultPlatform
		}

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

			if buildForSinglePlatform || len(service.Build.Platforms) == 0 {
				// if we're building for a single platform, we want to build for the platform we'll use to run the image
				// similarly, if no build platforms were explicitly specified, it makes sense to build for the platform
				// the image is designed for rather than allowing the builder to infer the platform
				service.Build.Platforms = []string{service.Platform}
			}
		}

View on GitHub (pinned to ddc4b044b6)

Solutions

Add the DOCKER_DEFAULT_PLATFORM value to the service's `build.platforms` list.
Or set an explicit service-level `platform:` so the env default no longer applies.
Or unset DOCKER_DEFAULT_PLATFORM for the compose invocation if the service should build for its configured platforms only.

Example fix

# before
services:
  api:
    build:
      platforms: [linux/amd64]
# with DOCKER_DEFAULT_PLATFORM=linux/arm64

# after
services:
  api:
    platform: linux/amd64
    build:
      platforms: [linux/amd64]

Defensive patterns

Strategy: validation

Validate before calling

# bash: check platform coverage before compose does
DEFAULT_PLAT="${DOCKER_DEFAULT_PLATFORM:-}"
if [ -n "$DEFAULT_PLAT" ]; then
  docker compose config --services | while read -r svc; do
    plats=$(docker compose config --format json 2>/dev/null | jq -r --arg s "$svc" '.services[$s].build.platforms // [] | join(",")')
    [ -z "$plats" ] && continue
    case ",$plats," in *",$DEFAULT_PLAT,"*) ;; *) echo "$svc build.platforms lacks $DEFAULT_PLAT" >&2; exit 2;; esac
  done
fi

Prevention

Set an explicit `platform:` on any service that also declares build.platforms.
Don't export DOCKER_DEFAULT_PLATFORM globally; scope it per command.

When it happens

Trigger: Setting DOCKER_DEFAULT_PLATFORM=linux/arm64 while a service's build section lists only `platforms: [linux/amd64]` and no service-level `platform:`. The env value is checked via slices.Contains against build.Platforms and misses.

Common situations: Apple Silicon or ARM CI runners that export DOCKER_DEFAULT_PLATFORM globally, combined with compose files pinned to amd64 builds; cross-build setups where the platform list was narrowed and the default env leaked in from a login shell or Docker Desktop setting.

Related errors

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