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

Error message

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

What it means

BuildOptions.Apply enforces that a service's resolved service.Platform (set via the platform: field on the service, the DOCKER_DEFAULT_PLATFORM env var applied earlier, or API options) is contained in the build.platforms list when that list is non-empty. This keeps the built image consistent with the platform the service will run on; a mismatch would produce an image for the wrong OS/architecture.

Source

Thrown at pkg/api/api.go:250

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
type CreateOptions struct {
	Build *BuildOptions
	// Services defines the services user interacts with
	Services []string
	// Remove legacy containers for services that are not defined in the project
	RemoveOrphans bool

View on GitHub (pinned to ddc4b044b6)

Solutions

Make service.platform match one of the entries in build.platforms (same os/arch string, e.g. linux/amd64)
Remove the service-level platform: key and let build.platforms drive the target
Add the desired platform to build.platforms
Run docker compose config to see the effective platform and platforms values side by side

Example fix

# before (compose.yaml)
services:
  web:
    platform: linux/amd64
    build:
      platforms: [linux/arm64]
# after
services:
  web:
    platform: linux/arm64
    build:
      platforms: [linux/arm64]

Defensive patterns

Strategy: validation

Validate before calling

// Reject platform/platforms mismatches before calling Apply:
for name, svc := range project.Services {
	if svc.Build == nil || svc.Platform == "" {
		continue
	}
	if len(svc.Build.Platforms) > 0 && !slices.Contains(svc.Build.Platforms, svc.Platform) {
		return fmt.Errorf("service %s: platform %s not in build.platforms", name, svc.Platform)
	}
}

Prevention

Pick one source of truth: either service.platform or build.platforms, not both
Script a lint that parses compose.yaml and cross-checks platform values
Run docker compose config before build in CI to surface the resolved platform

When it happens

Trigger: A service sets platform: linux/amd64 while build.platforms only contains linux/arm64; DOCKER_DEFAULT_PLATFORM is set to a value included in platforms for some services but a service also carries its own conflicting platform: key; API callers pass a platform in options that collides with the pinned build.platforms.

Common situations: Cross-arch projects where build.platforms is intentionally narrow but a service-level platform: was copied from another service; mixing the deprecated service platform syntax with the modern build.platforms syntax; renames or refactors that left a stale platform: behind.

Related errors

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