docker/cli · error

unable to prepare context

Error message

unable to prepare context: %s

What it means

Returned by runBuild (build.go:238) when build.GetContextFromLocalDir fails while resolving a local directory build context (ContextTypeLocal). This function locates the context directory and the Dockerfile within/relative to it. The wrapped error is formatted with %s (not %w), so the underlying cause is string-interpolated. Common causes: the path does not exist, is not a directory, or the Dockerfile cannot be found inside.

Solutions

1. Confirm the path is a readable directory: 'ls -la <path>'.
2. Run the build from the directory containing the Dockerfile, or use an absolute path.
3. If using -f, verify the Dockerfile exists: 'test -f <path>/Dockerfile'.
4. Check directory permissions and that the current user can traverse to it.

Example fix

# before (wrong working directory)
cd / && docker build myapp
# after
cd ~/projects && docker build myapp

// Verify the build context is a readable directory before invoking docker build.
func validateBuildContext(path string) error {
	info, err := os.Stat(path)
	if err != nil { return err }
	if !info.IsDir() { return fmt.Errorf("%s is not a directory", path) }
	return nil
}

if err := buildCmd.Execute(); err != nil {
	if strings.Contains(err.Error(), "unable to prepare context") && !strings.Contains(err.Error(), "STDIN") {
		// local context path is invalid; check existence and permissions
	}
}

When it happens

Trigger: Running 'docker build <path>' where <path> does not exist, is a file rather than a directory, or where the default Dockerfile (or one specified with -f) cannot be located relative to the context. Also when <path> exists but is not readable due to permissions.

Common situations: Running 'docker build .' from the wrong working directory; pointing at a path that is a single file instead of a directory; specifying -f with a Dockerfile name that does not exist in the context; symlink loops; permission-denied directories.

Related errors

• unable to open Dockerfile
• removing image ID file
• checking context
• 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/1486c2e62c994a4b. Report an issue: GitHub.

Appendix: source

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

	}
	if options.imageIDFile != "" {
		// Avoid leaving a stale file if we eventually fail
		if err := os.Remove(options.imageIDFile); err != nil && !os.IsNotExist(err) {
			return fmt.Errorf("removing image ID file: %w", err)
		}
	}

	switch contextType {
	case build.ContextTypeStdin:
		// buildCtx is tar archive. if stdin was dockerfile then it is wrapped
		buildCtx, relDockerfile, err = build.GetContextFromReader(dockerCli.In(), options.dockerfileName)
		if err != nil {
			return fmt.Errorf("unable to prepare context from STDIN: %w", err)
		}
	case build.ContextTypeLocal:
		contextDir, relDockerfile, err = build.GetContextFromLocalDir(options.context, options.dockerfileName)
		if err != nil {
			return fmt.Errorf("unable to prepare context: %s", err)
		}
		if strings.HasPrefix(relDockerfile, ".."+string(filepath.Separator)) {
			// Dockerfile is outside build-context; read the Dockerfile and pass it as dockerfileCtx
			dockerfileCtx, err = os.Open(options.dockerfileName)
			if err != nil {
				return fmt.Errorf("unable to open Dockerfile: %w", err)
			}
			defer dockerfileCtx.Close()
		}
	case build.ContextTypeGit:
		var tempDir string
		tempDir, relDockerfile, err = build.GetContextFromGitURL(options.context, options.dockerfileName)
		if err != nil {
			return fmt.Errorf("unable to prepare context: %w", err)
		}
		defer func() {
			_ = os.RemoveAll(tempDir)
		}()

View on GitHub (pinned to 4f84911bfe)