🚨 Docker Error Guide: 'unable to prepare context: path not found' — Fix Invalid Build Context Paths

Overview

Docker fails before reading the Dockerfile because the build context path you passed does not exist:

unable to prepare context: path "./app" not found

The final argument to docker build is the build context — a directory (or URL) whose contents are sent to the daemon. If that path does not resolve to an existing directory, Docker cannot assemble a context and stops immediately, before any Dockerfile is parsed.

Symptoms

• docker build fails instantly with unable to prepare context: path ... not found.
• No files are sent to the daemon; the build never starts.
• The path was mistyped, or the argument order put a flag value where the context should be.
• The command works from one directory but not another.

Common Root Causes

• Typo in the context path — ./app when the directory is ./apps or ./src.
• Wrong working directory — the relative context does not exist from where you ran the command.
• Missing context argument — a flag’s value was consumed as the context, or the trailing . was omitted.
• Argument order mistake — placing options after the context, so Docker treats the wrong token as the path.
• Deleted or not-yet-created directory — building against a path a previous step should have produced.
• Confusing -f with the context — passing the Dockerfile path as the context instead of a directory.

Diagnostic Workflow

Confirm the current directory and that the context path exists:

pwd
ls -ld ./app

Inspect the exact command; the context is the last positional argument:

history | tail -n 5

Rebuild with an explicit, verified context directory and a separate -f for the Dockerfile:

ls -ld .
docker build -f docker/Dockerfile -t myapp:1.4.2 .

If you intended a subdirectory context, verify it and pass it as the final argument:

ls -ld ./services/api
docker build -f ./services/api/Dockerfile -t myapp:1.4.2 ./services/api

Use plain progress output to confirm the context Docker resolved:

docker build --progress=plain -t myapp:1.4.2 .

Example Root Cause Analysis

An engineer copied a build command from notes and it failed:

unable to prepare context: path "app" not found

The command was:

docker build -t myapp:1.4.2 app

ls -ld app returned No such file or directory. The repository used src/ for application code, not app/ — the note was from a different project. Docker treated app as the build context directory, and since it did not exist, context preparation failed before the Dockerfile was ever read. Correcting the context to the actual directory fixed it:

docker build -t myapp:1.4.2 .

The takeaway: the last argument is a real directory that must exist; Docker validates it before anything else.

Prevention Best Practices

• Standardize on building from the repository root with . as the context so relative paths stay predictable.
• Put options before the context argument and keep the context (a directory) last.
• Verify the context directory exists (ls -ld) in scripts before invoking docker build.
• Keep -f (Dockerfile path) and the context argument mentally separate — one names a file, the other a directory.
• Document the canonical build command in the README so copied commands do not carry another project’s paths.

Quick Command Reference

pwd                                       # confirm working directory
ls -ld ./app                              # verify context path exists
docker build -t myapp:1.4.2 .             # build with current dir as context
docker build -f ./services/api/Dockerfile -t myapp:1.4.2 ./services/api
docker build --progress=plain -t myapp:1.4.2 .

Conclusion

unable to prepare context: path not found is Docker rejecting a build context directory that does not exist. It happens before parsing, so the fix is always about the path: correct the typo, run from the right directory, and keep the context argument last. Building from the repo root with . avoids nearly every case. Explore more build fixes in the Docker stack guides.