{"record":{"id":"266e56a63936bdfd","repo":"docker/compose","slug":"the-classic-builder-doesn-t-support-multi-arch-bui","errorCode":null,"errorMessage":"the classic builder doesn't support multi-arch build, set DOCKER_BUILDKIT=1 to use BuildKit","messagePattern":"the classic builder doesn't support multi-arch build, set DOCKER_BUILDKIT=1 to use BuildKit","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/compose/build_classic.go","lineNumber":134,"sourceCode":"\t\t\tservice := project.Services[names[i]]\n\t\t\timageRef := api.GetImageNameOrDefault(service, project.Name)\n\t\t\timageIDs[imageRef] = imageDigest\n\t\t}\n\t}\n\treturn imageIDs, err\n}\n\n//nolint:gocyclo\nfunc (s *composeService) doBuildImage(ctx context.Context, project *types.Project, service types.ServiceConfig, options api.BuildOptions) (string, error) {\n\tvar (\n\t\tbuildCtx      io.ReadCloser\n\t\tdockerfileCtx io.ReadCloser\n\t\tcontextDir    string\n\t\trelDockerfile string\n\t)\n\n\tif len(service.Build.Platforms) > 1 {\n\t\treturn \"\", fmt.Errorf(\"the classic builder doesn't support multi-arch build, set DOCKER_BUILDKIT=1 to use BuildKit\")\n\t}\n\tif service.Build.Privileged {\n\t\treturn \"\", fmt.Errorf(\"the classic builder doesn't support privileged mode, set DOCKER_BUILDKIT=1 to use BuildKit\")\n\t}\n\tif len(service.Build.AdditionalContexts) > 0 {\n\t\treturn \"\", fmt.Errorf(\"the classic builder doesn't support additional contexts, set DOCKER_BUILDKIT=1 to use BuildKit\")\n\t}\n\tif len(service.Build.SSH) > 0 {\n\t\treturn \"\", fmt.Errorf(\"the classic builder doesn't support SSH keys, set DOCKER_BUILDKIT=1 to use BuildKit\")\n\t}\n\tif len(service.Build.Secrets) > 0 {\n\t\treturn \"\", fmt.Errorf(\"the classic builder doesn't support secrets, set DOCKER_BUILDKIT=1 to use BuildKit\")\n\t}\n\n\tif service.Build.Labels == nil {\n\t\tservice.Build.Labels = make(map[string]string)\n\t}\n\tservice.Build.Labels[api.ImageBuilderLabel] = \"classic\"","sourceCodeStart":116,"sourceCodeEnd":152,"githubUrl":"https://github.com/docker/compose/blob/ddc4b044b62e9f715212ea4143fa830fac76382f/pkg/compose/build_classic.go#L116-L152","documentation":"When BuildKit is not in use (DOCKER_BUILDKIT=0, no buildx plugin, or COMPOSE_BAKE=false), compose falls back to the legacy builder API in doBuildImage. That API can only build a single platform for the host OS/architecture, so a service declaring more than one entry in build.platforms is rejected with a pointer to re-enable BuildKit. This is a capability gate on the classic path.","triggerScenarios":"docker compose build with COMPOSE_BAKE=false or DOCKER_BUILDKIT=0 while a service lists two or more platforms under build.platforms; buildx missing so compose silently downgraded to the classic builder.","commonSituations":"Users forcing the legacy builder for corporate/registry reasons but keeping multi-arch compose files; environments without the buildx plugin (minimal VMs, old Docker installs); setting DOCKER_BUILDKIT=0 to work around an unrelated issue and forgetting the platforms list.","solutions":["Re-enable BuildKit: unset DOCKER_BUILDKIT and ensure the buildx plugin (>= 0.17.0) is installed","Unset COMPOSE_BAKE=false so compose uses the bake/BuildKit path","Reduce build.platforms to the single host platform if the classic builder is mandatory","Install buildx: docker's get.docker.com script or a manual plugin download"],"exampleFix":"# before\n$ DOCKER_BUILDKIT=0 docker compose build   # platforms: [linux/amd64, linux/arm64]\n# after — option A\n$ unset DOCKER_BUILDKIT; unset COMPOSE_BAKE; docker compose build\n# after — option B (classic builder mandatory)\nservices:\n  web:\n    build:\n      platforms: [linux/amd64]   # host platform only\n","handlingStrategy":"validation","validationCode":"// Before routing a build to the classic builder:\nfor name, svc := range project.Services {\n\tif svc.Build == nil {\n\t\tcontinue\n\t}\n\tif len(svc.Build.Platforms) > 1 && classicBuilder() {\n\t\treturn fmt.Errorf(\"service %s needs BuildKit for multi-platform; unset DOCKER_BUILDKIT/COMPOSE_BAKE\", name)\n\t}\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never combine DOCKER_BUILDKIT=0 with multi-platform compose files","Install buildx so compose never silently downgrades to the classic builder","Document BuildKit as a hard requirement for projects using build.platforms"],"tags":["classic-builder","buildkit","platform","build"],"backgroundTag":null,"analyzedSha":"ddc4b044b62e9f715212ea4143fa830fac76382f","analyzedAt":"2026-08-15T13:31:42.319Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}