How to fix 'ADD failed: stat … no such file or directory'

What this error means

Docker shows “ADD failed: stat … no such file or directory” (or in BuildKit, “failed to compute cache key: … no such file or directory”) when the source path you reference in ADD or COPY cannot be found. The source must exist in one of:

• The build context you send with docker build <context-dir>
• A previous build stage filesystem when using COPY --from=<stage>

If Docker cannot find it in either, you get this error.

Quickstart: fastest checks

1. Confirm your build context

   • Run the build from the directory that contains the files you want to copy.
   • Example: docker build -t app . sends the current directory as context.
   • If you use -f path/to/Dockerfile, keep the context separate: docker build -f path/to/Dockerfile . (the last argument is the context).

2. Verify the source path is inside the context

   • Paths in ADD/COPY are relative to the context root, not to the Dockerfile’s location.
   • ADD src/ /app/src requires ./src to exist under the context directory.

3. Check .dockerignore

   • Ensure the file/dir you want is not ignored.
   • Use negation if needed: !dist/ to allow copying dist/.

4. Multistage COPY

   • If using COPY --from=builder /out /app, verify the stage name and the path actually exist in that stage.

5. Case sensitivity and globs

   • Linux paths are case-sensitive. Ensure patterns (e.g., COPY *.txt) actually match files.

6. Use plain progress to see context

   • docker buildx build --progress=plain . shows what’s sent and can hint at ignored files.

Minimal working example

This example succeeds, then we break it, then we fix it.

Files:

Dockerfile:

FROM alpine:3.20
WORKDIR /app
ADD hello.txt /app/hello.txt
CMD ["cat", "/app/hello.txt"]

hello.txt:

Hello from Docker build context

Build and run:

# build succeeds because hello.txt is in the context
docker build -t add-demo .
docker run --rm add-demo

Now break it with .dockerignore:

.dockerignore:

hello.txt

Rebuild:

# This will fail: source is ignored and not sent in the context
docker build -t add-demo .

Fix options:

• Remove the ignore entry, or
• Allow the file explicitly:

.dockerignore (fixed):

# ignore most files but keep hello.txt
*
!hello.txt

Rebuild:

docker build -t add-demo .
docker run --rm add-demo

Common causes and fixes

Multistage example (correct path from stage)

# Stage 1: build
FROM node:20-alpine AS builder
WORKDIR /src
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build --if-present && mkdir -p /out && cp -r dist/* /out/

# Stage 2: runtime
FROM nginx:alpine
# Correct: path exists in the builder stage filesystem
COPY --from=builder /out/ /usr/share/nginx/html/

• If /out/ doesn’t exist (e.g., build failed or path typo), COPY --from will report “no such file or directory”. Ensure the command creating /out ran and the path is correct.

Step-by-step diagnosis

1. Identify the missing path

   • Read the error: the fragment after stat is the missing source path.

2. Confirm it exists on your machine

   • ls -la <path> starting from the context directory.

3. Verify it’s in the context tar

   • Temporarily remove rules from .dockerignore or run docker buildx build --progress=plain . to observe what’s sent.

4. Check build flags

   • Ensure the last argument to docker build is the intended context. The -f Dockerfile path does not change the context.

5. Multistage checks

   • Confirm the stage name matches (AS builder then --from=builder).
   • In the stage, ensure the source path exists: add RUN ls -la /out for debugging.

6. Rebuild with a clean cache

   • If paths changed, use --no-cache to avoid misleading cache hits.

Pitfalls to avoid

• Confusing Dockerfile location with context root; they’re independent.
• Overly broad .dockerignore (e.g., **/*) that hides needed assets.
• Using ADD for remote URLs; prefer COPY and explicit RUN curl … for clarity and caching.
• Relying on shell expansions/quotes in Dockerfile paths; provide plain paths.
• Trailing slash confusion: ensure destination semantics are what you expect, but remember the error here is about the source.

Performance notes

• Keep the context small with .dockerignore but whitelist build artifacts you need.
• Prefer COPY over ADD unless you need tar auto-extraction; it’s clearer and avoids unintended cache invalidations.
• Group COPY operations by layer stability. Example: copy package.json first, run install, then copy source to maximize cache hits.
• Use multistage builds to copy only the final artifacts into the runtime image.
• Enable BuildKit (DOCKER_BUILDKIT=1) for parallelism and clearer diagnostics.

FAQ

• Why does it work on my machine but fail in CI?

  • CI often uses a different context (e.g., a subdirectory) or a stricter .dockerignore. Verify the CI working directory and build command.

• Can I copy files outside the context?

  • No. Docker intentionally forbids paths outside the context for security. Change the context or rearrange files.

• Do ENV/ARG variables expand in ADD/COPY?

  • Yes, variables from ARG and ENV can expand, but if expansion results in a non-existent path, you’ll still get the same error.

• BuildKit shows a different message. Is it the same issue?

  • Yes. BuildKit reports “failed to compute cache key … no such file or directory,” but the root cause is identical: missing source.