{"record":{"id":"2611ecafdce44403","repo":"docker/compose","slug":"the-classic-builder-doesn-t-support-additional-con","errorCode":null,"errorMessage":"the classic builder doesn't support additional contexts, set DOCKER_BUILDKIT=1 to use BuildKit","messagePattern":"the classic builder doesn't support additional contexts, set DOCKER_BUILDKIT=1 to use BuildKit","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/compose/build_classic.go","lineNumber":140,"sourceCode":"}\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\"\n\n\tdockerfileName := dockerFilePath(service.Build.Context, service.Build.Dockerfile)\n\tspecifiedContext := service.Build.Context\n\tprogBuff := s.stdout()\n\tbuildBuff := s.stdout()\n","sourceCodeStart":122,"sourceCodeEnd":158,"githubUrl":"https://github.com/docker/compose/blob/ddc4b044b62e9f715212ea4143fa830fac76382f/pkg/compose/build_classic.go#L122-L158","documentation":"On the classic build path, doBuildImage rejects any service declaring build.additional_contexts. Additional build contexts (named contexts passed to the Dockerfile via --build-context) are implemented only by BuildKit's builder; the legacy API accepts a single context tarball and cannot attach extra named sources, so compose fails fast with the DOCKER_BUILDKIT=1 hint.","triggerScenarios":"A compose service uses build.additional_contexts (e.g. mapping 'src' to another service's image or a local path for a COPY --from=src step) while the build is routed to the classic builder via DOCKER_BUILDKIT=0, COMPOSE_BAKE=false, or a missing buildx plugin.","commonSituations":"Multi-service build sharing sources through named contexts; COPY --from=other-service patterns; hosts where BuildKit was disabled for firewall reasons but the compose file assumes modern features.","solutions":["Enable BuildKit (unset DOCKER_BUILDKIT / COMPOSE_BAKE; ensure buildx installed) so additional contexts work","If stuck on the classic builder, inline the extra source into the main build context (COPY from within the context) and remove additional_contexts","Pre-build the dependency image and reference it by tag instead of a named context"],"exampleFix":"# before (compose.yaml)\nservices:\n  app:\n    build:\n      context: .\n      additional_contexts:\n        deps: ../deps\n# + DOCKER_BUILDKIT=0 -> error\n# after\n$ unset DOCKER_BUILDKIT\n$ docker compose build app\n","handlingStrategy":"validation","validationCode":"// Guard before a classic-path build:\nfor name, svc := range project.Services {\n\tif svc.Build != nil && len(svc.Build.AdditionalContexts) > 0 && classicBuilder() {\n\t\treturn fmt.Errorf(\"service %s requires BuildKit for additional_contexts\", name)\n\t}\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use additional_contexts only on BuildKit-enabled hosts; provide a legacy variant of the compose file if needed","Prefer referencing pre-built dependency images over named contexts in mixed environments","Smoke-test builds with DOCKER_BUILDKIT unset to confirm the toolchain you actually rely on"],"tags":["classic-builder","buildkit","build-context","build"],"backgroundTag":null,"analyzedSha":"ddc4b044b62e9f715212ea4143fa830fac76382f","analyzedAt":"2026-08-15T13:31:42.319Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}