docker/compose · error

unable to prepare context: path %q not found

Error message

unable to prepare context: path %q not found

What it means

The default branch of the context-type switch: DetectContextType returned a value that is neither stdin, local, git, nor remote — in practice this happens when the context path does not exist on disk (DetectContextType classifies missing local paths into a 'not found' bucket). The message includes the offending path so the misconfiguration is obvious.

Source

Thrown at pkg/compose/build_classic.go:196

			defer dockerfileCtx.Close() //nolint:errcheck
		}
	case build.ContextTypeGit:
		var tempDir string
		tempDir, relDockerfile, err = build.GetContextFromGitURL(specifiedContext, 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, 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{

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Check that the exact path in the error exists: `ls -la '<path from message>'` from your compose invocation directory
2. Create the missing directory or correct the `build.context` value / the variable feeding it
3. Run compose from the repo root (or set `--project-directory`) so relative contexts resolve as intended

Example fix

# before
services:
  app:
    build:
      context: ${APP_CTX}   # unset -> bad path

# after
services:
  app:
    build:
      context: ${APP_CTX:-./app}

if _, err := os.Stat(svc.Build.Context); err != nil {
    return fmt.Errorf("build context path %q not found — check working dir and interpolation", svc.Build.Context)
}

When it happens

Trigger: `docker compose build` where `build.context` names a path that does not exist and cannot be classified — e.g. a directory never created, an interpolated empty/na variable producing '.', or a path with a typo after moving files.

Common situations: Running compose from the wrong working directory so relative contexts don't resolve; generated Compose files referencing build dirs that a generator step was supposed to create; Windows path separators in context values on Linux.

Related errors

• unable to prepare context: %w
• building from STDIN is not supported
• checking context: %w
• invalid ssh key %q
• failed to parse env_file %s: %w

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