docker/cli · error

unable to prepare context

Error message

unable to prepare context: %w

What it means

Returned by runBuild (build.go:252) when build.GetContextFromGitURL fails while preparing a git-URL build context (ContextTypeGit). This clones/fetches the remote git repository into a temp directory and locates the Dockerfile within it. Failure indicates the git operation or subsequent Dockerfile resolution failed.

Solutions

1. Clone the repo manually first to validate access: 'git clone <url>' and confirm it succeeds.
2. Ensure credentials are configured (SSH key, credential helper, or HTTPS token) for private repos.
3. Verify the #:path and #:branch fragment syntax matches actual branches/dirs in the repo.
4. Confirm git is installed and reachable: 'git --version'.

Example fix

# before (private repo, no credentials)
docker build git@github.com:org/private.git
# after (configure SSH key, or clone then build locally)
git clone git@github.com:org/private.git && docker build private

// Probe git access for a remote context URL before building.
func validateGitContext(url string) error {
	cmd := exec.Command("git", "ls-remote", url)
	return cmd.Run()
}

if err := buildCmd.Execute(); err != nil {
	if strings.Contains(err.Error(), "unable to prepare context") && strings.HasPrefix(ctx, "http") {
		// git context fetch failed; verify credentials and network
	}
}

When it happens

Trigger: Running 'docker build https://github.com/org/repo.git[#:subdir]' or 'docker build git@...' where the URL is unreachable, the repo does not exist, authentication fails, the referenced subdir/branch does not exist, or git is not installed on PATH. Also fires if the cloned repo contains no Dockerfile at the expected path.

Common situations: Private repo without configured credentials/SSH key; typo in the URL; branch/tag referenced after '#' does not exist; corporate proxy/firewall blocking git; git binary missing or too old; the repo has no Dockerfile in the root or specified subdir.

Related errors

• unexpected response from tenant
• error establishing connection to trust repository
• no signatures or cannot access
• no signers for
• failed to configure transport

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

Appendix: source

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

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

View on GitHub (pinned to 4f84911bfe)