{"record":{"id":"9b1be8534d9fba9d","repo":"docker/compose","slug":"unable-to-prepare-context-w","errorCode":null,"errorMessage":"unable to prepare context: %w","messagePattern":"unable to prepare context: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/compose/build_classic.go","lineNumber":170,"sourceCode":"\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\n\tcontextType, err := build.DetectContextType(specifiedContext)\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\n\tswitch contextType {\n\tcase build.ContextTypeStdin:\n\t\treturn \"\", fmt.Errorf(\"building from STDIN is not supported\")\n\tcase build.ContextTypeLocal:\n\t\tcontextDir, relDockerfile, err = build.GetContextFromLocalDir(specifiedContext, dockerfileName)\n\t\tif err != nil {\n\t\t\treturn \"\", fmt.Errorf(\"unable to prepare context: %w\", err)\n\t\t}\n\t\tif strings.HasPrefix(relDockerfile, \"..\"+string(filepath.Separator)) {\n\t\t\t// Dockerfile is outside build-context; read the Dockerfile and pass it as dockerfileCtx\n\t\t\tdockerfileCtx, err = os.Open(dockerfileName)\n\t\t\tif err != nil {\n\t\t\t\treturn \"\", fmt.Errorf(\"unable to open Dockerfile: %w\", err)\n\t\t\t}\n\t\t\tdefer dockerfileCtx.Close() //nolint:errcheck\n\t\t}\n\tcase build.ContextTypeGit:\n\t\tvar tempDir string\n\t\ttempDir, relDockerfile, err = build.GetContextFromGitURL(specifiedContext, dockerfileName)\n\t\tif err != nil {\n\t\t\treturn \"\", fmt.Errorf(\"unable to prepare context: %w\", err)\n\t\t}\n\t\tdefer func() {\n\t\t\t_ = os.RemoveAll(tempDir)\n\t\t}()","sourceCodeStart":152,"sourceCodeEnd":188,"githubUrl":"https://github.com/docker/compose/blob/ddc4b044b62e9f715212ea4143fa830fac76382f/pkg/compose/build_classic.go#L152-L188","documentation":"Wraps the error from build.GetContextFromLocalDir when the detected context type is a local path but the directory (or the Dockerfile within it) cannot be resolved. GetContextFromLocalDir validates that the context is an existing directory and that the absolute Dockerfile path lives under it; any failure is re-wrapped with 'unable to prepare context' plus the underlying cause.","triggerScenarios":"`docker compose build` where build.context points to a non-existent or non-directory path, or build.dockerfile names a file that cannot be stat'ed relative to the context (e.g. context typo, wrong working directory, missing checkout of a monorepo sibling dir).","commonSituations":"Context paths that depend on where you run compose from (relative paths like ../backend); monorepo checkouts where only part was cloned; Dockerfile key misspelled (`dockerfile: Dockerfile.prod` when the file is named differently); case-sensitivity issues moving from macOS to Linux CI.","solutions":["Verify the context directory exists: `ls <context path>` from the same directory you run `docker compose build`","Fix the `build.context` / `build.dockerfile` values in the Compose file (check spelling, case, and relative-path base)","If the path is interpolated (`context: ${VAR}`), confirm the variable is set and non-empty in the shell or .env file"],"exampleFix":"# before\nservices:\n  app:\n    build:\n      context: ./backendd   # typo\n\n# after\nservices:\n  app:\n    build:\n      context: ./backend","handlingStrategy":"validation","validationCode":"info, err := os.Stat(svc.Build.Context)\nif err != nil || !info.IsDir() {\n    return fmt.Errorf(\"build context %q is not an existing directory\", svc.Build.Context)\n}\nif df := svc.Build.Dockerfile; df != \"\" {\n    if _, err := os.Stat(filepath.Join(svc.Build.Context, df)); err != nil {\n        return fmt.Errorf(\"dockerfile %q not found in context: %w\", df, err)\n    }\n}","typeGuard":null,"tryCatchPattern":"if err := compose.Build(ctx, project, opts); err != nil {\n    if strings.Contains(err.Error(), \"unable to prepare context\") {\n        // surface the chained fs error, point user at context/dockerfile paths\n    }\n}","preventionTips":["Always run compose from the repo root or set --project-directory explicitly","Add a preflight check (make target) that stats every build.context and dockerfile"],"tags":["build","context","filesystem","path"],"backgroundTag":null,"analyzedSha":"ddc4b044b62e9f715212ea4143fa830fac76382f","analyzedAt":"2026-08-15T13:31:42.319Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}