{"record":{"id":"f9684369da438227","repo":"docker/cli","slug":"checking-context-w","errorCode":null,"errorMessage":"checking context: %w","messagePattern":"checking context: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/image/build.go","lineNumber":275,"sourceCode":"\t\tcontextDir = tempDir\n\tcase build.ContextTypeRemote:\n\t\tbuildCtx, relDockerfile, err = build.GetContextFromURL(progBuff, options.context, options.dockerfileName)\n\t\tif err != nil && options.quiet {\n\t\t\t_, _ = fmt.Fprintln(dockerCli.Err(), progBuff)\n\t\t}\n\tdefault:\n\t\treturn fmt.Errorf(\"unable to prepare context: path %q not found\", options.context)\n\t}\n\n\t// read from a directory into tar archive\n\tif buildCtx == nil {\n\t\texcludes, err := build.ReadDockerignore(contextDir)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\n\t\tif err := build.ValidateContextDirectory(contextDir, excludes); err != nil {\n\t\t\treturn fmt.Errorf(\"checking context: %w\", err)\n\t\t}\n\n\t\t// And canonicalize dockerfile name to a platform-independent one\n\t\trelDockerfile = filepath.ToSlash(relDockerfile)\n\n\t\texcludes = build.TrimBuildFilesFromExcludes(excludes, relDockerfile, options.dockerfileFromStdin())\n\t\tbuildCtx, err = archive.TarWithOptions(contextDir, &archive.TarOptions{\n\t\t\tExcludePatterns: excludes,\n\t\t\tChownOpts:       &archive.ChownOpts{UID: 0, GID: 0},\n\t\t})\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t}\n\n\t// replace Dockerfile if it was added from stdin or a file outside the build-context, and there is archive context\n\tif dockerfileCtx != nil && buildCtx != nil {\n\t\tbuildCtx, relDockerfile, err = build.AddDockerfileToBuildContext(dockerfileCtx, buildCtx)","sourceCodeStart":257,"sourceCodeEnd":293,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/image/build.go#L257-L293","documentation":"Returned by runBuild (build.go:275) when build.ValidateContextDirectory fails after reading .dockerignore excludes. ValidateContextDirectory walks the context directory to verify it is usable (e.g., detecting files that are too large, unreadable, or otherwise problematic for tarring and upload). The wrapped error carries the specifics.","triggerScenarios":"Building with a local context directory that contains files ValidateContextDirectory rejects: files exceeding the context-size guard, unreadable files/dirs due to permissions, symlink loops, special device files, or a context directory whose total size triggers the 'context too large' warning turned error. Also triggered when the directory cannot be walked at all.","commonSituations":"Building from a project root that contains a huge directory (node_modules, .git, build artifacts, data dumps) not covered by .dockerignore; files owned by another user with no read permission; broken symlinks pointing to deleted targets; building inside a FUSE/mount with restricted traversal.","solutions":["Add a .dockerignore excluding large/unneeded dirs (node_modules, .git, dist, data, *.log).","Check for permission errors: 'find <context> -type f ! -readable' and fix ownership/permissions.","Remove broken symlinks: 'find -L <context> -type l -delete' after review.","Build from a subdirectory or a cleaned checkout to shrink the context."],"exampleFix":"# before: huge unignored directory\necho 'node_modules' > .dockerignore-ignore  # wrong file\n# after: proper .dockerignore\ncat > .dockerignore <<EOF\nnode_modules\n.git\ndist\n*.log\nEOF\ndocker build .","handlingStrategy":"validation","validationCode":"// Pre-check the context directory for obvious problems (size, permissions).\nfunc validateContextDir(dir string) error {\n\tvar total int64\n\treturn filepath.Walk(dir, func(p string, info os.FileInfo, err error) error {\n\t\tif err != nil { return err }\n\t\ttotal += info.Size()\n\t\treturn nil\n\t})\n}","typeGuard":null,"tryCatchPattern":"if err := buildCmd.Execute(); err != nil {\n\tif strings.Contains(err.Error(), \"checking context\") {\n\t\t// context dir has problematic files; trim with .dockerignore or fix permissions\n\t}\n}","preventionTips":["Maintain a .dockerignore excluding node_modules, .git, build artifacts, and logs.","Run 'du -sh <context>' and 'find <context> ! -readable' before building.","Build from a cleaned subdirectory to keep the context small."],"tags":["build","context-validation","dockerignore","filesystem"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}