docker/cli · error

unable to prepare context: path

Error message

unable to prepare context: path %q not found

What it means

Returned by runBuild (build.go:264) in the default branch of the context-type switch, meaning build.DetectContextType returned a value that is none of stdin, local, git, or remote. In practice DetectContextType classifies any non-URL, non-git, non-'-' argument as local, so reaching the default branch implies the path does not exist as a local file/dir and did not match the other detectors - effectively an unrecognized/missing context argument.

Solutions

1. Confirm the context argument is a supported type: local directory path, '-', git URL (https/ssh), or http(s) URL.
2. If it is meant to be a local path, verify it exists: 'ls <path>'.
3. For URL contexts, use http(s):// or git-compliant URLs only.
4. Upgrade the CLI if you expect a newer context type (e.g., a new scheme) to be recognized.

Example fix

# before (unsupported scheme)
docker build ftp://example.com/repo
# after (https URL or local path)
docker build https://example.com/repo.git
docker build ./myapp

// Classify a context argument before passing it to docker build.
func classifyContext(arg string) error {
	switch {
	case arg == "-":
		return nil
	case strings.HasPrefix(arg, "http://"), strings.HasPrefix(arg, "https://"), strings.HasPrefix(arg, "git@"), strings.HasPrefix(arg, "git://"):
		return nil
	case fileExists(arg):
		return nil
	default:
		return fmt.Errorf("unsupported context: %q", arg)
	}
}

if err := buildCmd.Execute(); err != nil {
	if strings.Contains(err.Error(), "path") && strings.Contains(err.Error(), "not found") {
		// context argument is neither a local path nor a supported URL
	}
}

When it happens

Trigger: Passing a build context argument that is not a directory, not '-', not a URL, and not a git URL, yet also does not exist on the filesystem so that it was not classified as local. This is rare because most non-existent paths still fall into the local branch and fail later at 331; the default branch is reached for truly unclassified inputs (e.g., unusual schemes or future context types).

Common situations: Using an unsupported URL scheme (e.g., 'ftp://...'); passing a path with characters that defeat the local detector; version mismatch where a newer context type is not handled by this CLI build; extremely unusual inputs like empty strings in some edge cases.

Related errors

• docker endpoint configuration is required
• unrecognized config key
• failed to retrieve context tls info: ca.pem seems invalid
• no valid private key found
• cannot find docker endpoint in context

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

Appendix: source

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

			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)
		}()
		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{

View on GitHub (pinned to 4f84911bfe)