{"record":{"id":"7bc630c96d202344","repo":"docker/compose","slug":"service-q-build-platforms-does-not-support-value-7bc630","errorCode":null,"errorMessage":"service %q build.platforms does not support value set by DOCKER_DEFAULT_PLATFORM: %s","messagePattern":"service %q build\\.platforms does not support value set by DOCKER_DEFAULT_PLATFORM: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/api/api.go","lineNumber":244,"sourceCode":"\tSBOM string\n\t// Out is the stream to write build progress\n\tOut io.Writer\n}\n\n// Apply mutates project according to build options\nfunc (o BuildOptions) Apply(project *types.Project) error {\n\tplatform := project.Environment[\"DOCKER_DEFAULT_PLATFORM\"]\n\tfor name, service := range project.Services {\n\t\tif service.Provider == nil && service.Image == \"\" && service.Build == nil {\n\t\t\treturn fmt.Errorf(\"invalid service %q. Must specify either image or build\", name)\n\t\t}\n\n\t\tif service.Build == nil {\n\t\t\tcontinue\n\t\t}\n\t\tif platform != \"\" {\n\t\t\tif len(service.Build.Platforms) > 0 && !slices.Contains(service.Build.Platforms, platform) {\n\t\t\t\treturn fmt.Errorf(\"service %q build.platforms does not support value set by DOCKER_DEFAULT_PLATFORM: %s\", name, platform)\n\t\t\t}\n\t\t\tservice.Platform = platform\n\t\t}\n\t\tif service.Platform != \"\" {\n\t\t\tif len(service.Build.Platforms) > 0 && !slices.Contains(service.Build.Platforms, service.Platform) {\n\t\t\t\treturn fmt.Errorf(\"service %q build configuration does not support platform: %s\", name, service.Platform)\n\t\t\t}\n\t\t}\n\n\t\tservice.Build.Pull = service.Build.Pull || o.Pull\n\t\tservice.Build.NoCache = service.Build.NoCache || o.NoCache\n\n\t\tproject.Services[name] = service\n\t}\n\treturn nil\n}\n\n// CreateOptions group options of the Create API","sourceCodeStart":226,"sourceCodeEnd":262,"githubUrl":"https://github.com/docker/compose/blob/ddc4b044b62e9f715212ea4143fa830fac76382f/pkg/api/api.go#L226-L262","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# shell — before\nexport DOCKER_DEFAULT_PLATFORM=linux/arm64\n# shell — after (option A: unset for this build)\nunset DOCKER_DEFAULT_PLATFORM\n# compose.yaml — after (option B: declare support)\nservices:\n  web:\n    build:\n      platforms:\n        - linux/amd64\n        - linux/arm64\n","handlingStrategy":"validation","validationCode":"// Before building, confirm the env platform is declared:\nplatform := os.Getenv(\"DOCKER_DEFAULT_PLATFORM\")\nfor name, svc := range project.Services {\n\tif svc.Build == nil || platform == \"\" {\n\t\tcontinue\n\t}\n\tif len(svc.Build.Platforms) > 0 && !slices.Contains(svc.Build.Platforms, platform) {\n\t\treturn fmt.Errorf(\"service %s: add %s to build.platforms or unset DOCKER_DEFAULT_PLATFORM\", name, platform)\n\t}\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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"],"tags":["platform","environment","build","validation"],"backgroundTag":null,"analyzedSha":"ddc4b044b62e9f715212ea4143fa830fac76382f","analyzedAt":"2026-08-15T13:31:42.319Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}