docker/cli · error

checking context

Error message

checking context: %w

What it means

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.

Solutions

1. Add a .dockerignore excluding large/unneeded dirs (node_modules, .git, dist, data, *.log).
2. Check for permission errors: 'find <context> -type f ! -readable' and fix ownership/permissions.
3. Remove broken symlinks: 'find -L <context> -type l -delete' after review.
4. Build from a subdirectory or a cleaned checkout to shrink the context.

Example fix

# before: huge unignored directory
echo 'node_modules' > .dockerignore-ignore  # wrong file
# after: proper .dockerignore
cat > .dockerignore <<EOF
node_modules
.git
dist
*.log
EOF
docker build .

// Pre-check the context directory for obvious problems (size, permissions).
func validateContextDir(dir string) error {
	var total int64
	return filepath.Walk(dir, func(p string, info os.FileInfo, err error) error {
		if err != nil { return err }
		total += info.Size()
		return nil
	})
}

if err := buildCmd.Execute(); err != nil {
	if strings.Contains(err.Error(), "checking context") {
		// context dir has problematic files; trim with .dockerignore or fix permissions
	}
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• removing image ID file
• unable to prepare context
• unable to open Dockerfile
• source can not be empty
• destination can not be empty

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/f9684369da438227. Report an issue: GitHub.

Appendix: source

Thrown at cli/command/image/build.go:275

		contextDir = tempDir
	case build.ContextTypeRemote:
		buildCtx, relDockerfile, err = build.GetContextFromURL(progBuff, options.context, options.dockerfileName)
		if err != nil && options.quiet {
			_, _ = fmt.Fprintln(dockerCli.Err(), progBuff)
		}
	default:
		return fmt.Errorf("unable to prepare context: path %q not found", options.context)
	}

	// read from a directory into tar archive
	if buildCtx == nil {
		excludes, err := build.ReadDockerignore(contextDir)
		if err != nil {
			return err
		}

		if err := build.ValidateContextDirectory(contextDir, excludes); err != nil {
			return fmt.Errorf("checking context: %w", err)
		}

		// And canonicalize dockerfile name to a platform-independent one
		relDockerfile = filepath.ToSlash(relDockerfile)

		excludes = build.TrimBuildFilesFromExcludes(excludes, relDockerfile, options.dockerfileFromStdin())
		buildCtx, err = archive.TarWithOptions(contextDir, &archive.TarOptions{
			ExcludePatterns: excludes,
			ChownOpts:       &archive.ChownOpts{UID: 0, GID: 0},
		})
		if err != nil {
			return err
		}
	}

	// replace Dockerfile if it was added from stdin or a file outside the build-context, and there is archive context
	if dockerfileCtx != nil && buildCtx != nil {
		buildCtx, relDockerfile, err = build.AddDockerfileToBuildContext(dockerfileCtx, buildCtx)

View on GitHub (pinned to 4f84911bfe)