Docker COPY Failed: Fix “File Not Found in Build Context”

The build command defines the context#

Docker’s build context documentation defines a context as the set of files the builder can access. In this command:

1
docker build -f docker/Dockerfile .

. is the context, so COPY can read files under the current repository directory. docker/Dockerfile is only the Dockerfile location.

In this command:

1
docker build -f apps/web/Dockerfile apps/web

apps/web is the context. A COPY package.json . instruction now looks for apps/web/package.json, while a source such as COPY package.json /app/ cannot read a package file that lives at the repository root. Moving the Dockerfile does not expand the files available to the builder.

That distinction explains many errors that look like a typo in COPY. If the source is outside the context, changing COPY ../package.json will not make it legal. Docker deliberately prevents a Dockerfile from reaching above the context boundary.

Do not confuse the Dockerfile with the context#

The final argument and -f can refer to different inputs. In particular, - can mean a Dockerfile read from stdin and leave the build with no filesystem context:

In the second command, the Dockerfile is piped as a text file and - is the context. A local file can exist beside the command and still be unavailable to COPY. If you need a Dockerfile from stdin, keep a filesystem path as the final context argument and verify that the command uses it.

Check .dockerignore before changing COPY#

Docker reads .dockerignore from the root of the build context. The file can exclude a path that exists on disk, so a repository listing alone is not enough to prove that Docker can copy it.

For example, with this layout:

1
.
2
├── .dockerignore
3
├── package.json
4
├── pnpm-lock.yaml
5
├── apps/
6
│   └── web/
7
│       ├── Dockerfile
8
│       └── src/

and this command:

1
docker build -f apps/web/Dockerfile .

the Dockerfile can use repository-root files:

1
FROM node:22-alpine AS build
2
WORKDIR /app
3

4
COPY package.json pnpm-lock.yaml ./
5
COPY apps/web ./apps/web

But a .dockerignore rule such as apps/web or **/src can remove the exact source needed by the second COPY. Docker’s copy-ignored-file build check documents this failure mode explicitly: a COPY or ADD source that is excluded by .dockerignore is unavailable to the instruction.

Inspect the ignore file at the context root, not only beside the Dockerfile:

1
sed -n '1,240p' .dockerignore

Then check whether the pattern excludes the source or a parent directory. Remove or narrow the rule only if the file belongs in the image. Excluding secrets, local build output, and dependency directories is usually intentional; the fix is to copy the required source or build artifact explicitly, not to remove every ignore rule.

Check Dockerfile-specific ignore files#

The active ignore file can be beside the selected Dockerfile. With docker build -f apps/web/Dockerfile ., Docker uses apps/web/Dockerfile.dockerignore when it exists; that file takes precedence over .dockerignore at the context root. Inspect the file that matches the selected Dockerfile before assuming the root ignore file is active.

For a quick comparison, replace the paths with the Dockerfile and context used by the failing build:

1
for ignore_file in apps/web/Dockerfile.dockerignore .dockerignore; do
2
  if [ -f "$ignore_file" ]; then
3
    echo "== $ignore_file =="
4
    sed -n '1,240p' "$ignore_file"
5
  fi
6
done

A reliable diagnosis sequence#

Use the same working directory and command that CI uses:

1. Print the context. Identify the final path argument after all flags. Resolve it to an absolute directory.
2. Locate the source from that root. If the Dockerfile says COPY apps/web/package.json ./, verify that the file is at <context>/apps/web/package.json.
3. Read the active ignore file. Start with <Dockerfile>.dockerignore beside the selected Dockerfile; if it is absent, read .dockerignore at the context root.
4. Check case exactly. Linux builders distinguish Package.json from package.json, even when a local macOS filesystem appears less strict.
5. Use one explicit build command. Do not debug a local root context while CI uses a subdirectory context.
6. Re-check the next COPY. Fixing the first missing source can expose another path that is outside the same boundary.

The Docker CLI reference describes the positional PATH, URL, or - argument as the build context and notes that paths outside it cannot be used by COPY. Keep that boundary in the build command rather than relying on a developer’s current directory by accident.

Choose a context that matches the build#

There are two common layouts, and each is valid when the COPY paths match it.

1
docker build -f apps/web/Dockerfile .

1
docker build -f Dockerfile apps/web

Avoid the tempting fixes#

• Do not use ../ in COPY to escape the context. Docker filters paths outside the context.
• Do not move the Dockerfile and assume the context moved with it.
• Do not delete .dockerignore wholesale just to make a build pass.
• Do not make a local command use . while a deployment script uses a nested context.
• Do not copy the entire repository when a specific source path or generated artifact is sufficient.

If the missing file is generated, make that generation step happen before docker build and verify the generated file is not ignored. If the file is a secret, inject it through the supported build or runtime secret mechanism rather than copying it into an image layer.

FAQ#