Docker COPY failed source file missing from build context

What this failure means

Docker COPY or ADD instruction failed because the source file does not exist in the build context. The file may be excluded by .dockerignore or the path is incorrect.

Symptoms

Faultline looks for one or more of these log fragments:

COPY failed
COPY failed: stat
failed: file not found in build context
ADD failed: file not found
no such file or directory
Step [0-9]+ : COPY

Diagnosis

Docker builds use a build context that includes only files and directories specified or not excluded. Common causes:

• The source file path in COPY or ADD instruction does not exist relative to the build context root.
• The file is excluded by .dockerignore but the Dockerfile tries to copy it anyway.
• The build context path is wrong (e.g., using /app or an absolute path instead of a relative path).
• A build step generates the file but the COPY runs before that step completes.
• The repository structure does not match what the Dockerfile expects.

The error appears as COPY failed: file not found or file not found in build context.

Fix steps

1. Verify the exact relative path exists in the build context:

   docker build --no-cache -t test . 2>&1 | head -20
   ls -la <source-file>
   

2. Check .dockerignore for patterns that may be excluding the file:

   cat .dockerignore
   

3. Update the COPY instruction in the Dockerfile to use the correct relative path:

   # Before (wrong)
   COPY /app/src/main.go .
   
   # After (correct)
   COPY src/main.go .
   

4. If the file is generated during build, ensure it’s created in an earlier stage and either copied from that stage (multi-stage) or not excluded from the context.

5. Re-run docker build with explicit context path:

   docker build -t myimage:latest .
   

Validation

• docker build completes without COPY failed errors.

• List files in the running container to confirm they were copied:

  docker run --rm myimage:latest ls -la /app
  

Why it matters

Docker build failures block the entire CI/CD pipeline and prevent deployments. Missing files in the build context usually indicate an incorrect Dockerfile or incorrect working directory assumptions.

Prevention

• Use relative paths in COPY instructions.
• Test the Dockerfile locally with the same repository structure.
• Keep .dockerignore minimal and intentional.
• Document the expected repository layout in README.md.

Try it locally

docker build -t test .
ls -la .dockerignore
docker build -t test .
docker run --rm test ls -la /app

How Faultline detects it

Use faultline explain dockerfile-copy-source-missing to see the full playbook.

faultline analyze build.log
faultline explain dockerfile-copy-source-missing

Generated from playbooks/bundled/log/build/dockerfile-copy-source-missing.yaml. Do not edit directly.