service %q build configuration does not support platform: %s

Error message

service %q build configuration does not support platform: %s

What it means

A service sets `platform:` to a value that is not in its build section's `platforms:` list. applyPlatforms validates every explicitly set service platform against the build platform list and errors out, because building would not produce an image runnable on the requested platform.

Source

Thrown at cmd/compose/options.go:76

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}
			}
		}

		// services can specify that they should be built for multiple platforms, which can be used
		// with `docker compose build` to produce a multi-arch image
		// other cases, such as `up` and `run`, need a single architecture to actually run
		// if there is only a single platform present (which might have been inferred
		// from service.Platform above), it will be used, even if it requires emulation.
		// if there's more than one platform, then the list is cleared so that the builder
		// can decide.

View on GitHub (pinned to ddc4b044b6)

Solutions

Make the strings match exactly: add the platform value to build.platforms (watch variant suffixes like /v8).
Or change/remove the service `platform:` key if any of the build platforms is fine.
Verify with `docker compose config` that the resolved platform matches one entry verbatim.

Example fix

# before
services:
  api:
    platform: linux/arm64
    build:
      platforms: [linux/amd64, linux/arm64/v8]

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

Defensive patterns

Strategy: validation

Validate before calling

# bash: verify service platform is in build.platforms
for svcplat in $(docker compose config --format json | jq -r '.services | to_entries[] | select(.value.platform and .value.build.platforms) | "\(.key) \(.value.platform) \(.value.build.platforms | join(","))"'); do
  set -- $svcplat; svc=$1; plat=$2; plats=$3
  case ",$plats," in *",$plat,"*) ;; *) echo "$svc: platform $plat not in [$plats]" >&2; exit 2;; esac
done

Prevention

Use identical platform strings (including /v8 variants) in platform and build.platforms.
Run `docker compose config` in CI to fail on invalid platform combos before deploy.

When it happens

Trigger: Declaring `platform: linux/arm64` on a service whose build.platforms only contains linux/amd64; or setting platform via DOCKER_DEFAULT_PLATFORM after it passed the first check but then narrowing build.platforms so it no longer contains the resolved value.

Common situations: Copy-pasted compose files between amd64 and arm64 teams where one side edited build.platforms but not the platform key; multi-arch build matrices where a stale platform string (e.g. `linux/arm64/v8` vs `linux/arm64`) doesn't textually match the platforms entry.

Related errors

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