docker/compose · error

checking context: %w

Error message

checking context: %w

What it means

Wraps build.ValidateContextDirectory, which walks the local context directory (after .dockerignore excludes) and verifies every file is usable for tarring. It fails when the walk hits unreadable files/directories (permission denied), or special entries that cannot be represented. The underlying walk error is chained after 'checking context:'.

Source

Thrown at pkg/compose/build_classic.go:207

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

	// 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, false)
		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 ddc4b044b6)

Solutions

1. Inspect the chained error for the offending path, then fix ownership/permissions (e.g. sudo chown -R $(id -u):$(id -g) <path>)
2. Add the problematic files/dirs to .dockerignore so they are excluded before validation
3. Clean stray build artifacts (sockets, root-owned temp files) out of the context directory

Example fix

# .dockerignore (after)
data/
*.sock
tmp/

// walk the context honoring .dockerignore and report unreadable entries early
excludes, _ := build.ReadDockerignore(ctxDir)
_ = filepath.WalkDir(ctxDir, func(p string, d fs.DirEntry, err error) error {
    if err != nil { return fmt.Errorf("%s: %w", p, err) }
    return nil
})

When it happens

Trigger: `docker compose build` (classic path, local context) where the context contains unreadable files not excluded by .dockerignore — root-owned artifacts from previous container runs, sockets/FIFOs in the build dir, or directories with mode 000.

Common situations: Building directly in a data dir where bind-mounted containers left root-owned files; node_modules or target/ with odd ownership after a containerized toolchain ran; leftover unix sockets in a context directory.

Related errors

• building from STDIN is not supported
• unable to prepare context: %w
• unable to open Dockerfile: %w
• unable to prepare context: path %q not found
• invalid ssh key %q

AI-assisted analysis of docker/compose@ddc4b044b6 (2026-08-15). Data as JSON: /api/errors/8929487d01c248ce. Report an issue: GitHub.