How to fix COPY failed: file not found in build context or excluded by .dockerignore in Docker

DockerBEGINNERLOWUpdated Dec 6, 2025· 217 views

The file you are trying to COPY does not exist in the build context or is excluded by .dockerignore. Check the file path relative to the Dockerfile and your .dockerignore rules.

Quick fix

Fixes COPY failed: file not found in build context or excluded by .dockerignore

# List files in build context directory
ls -la path/to/file

# Build context is the path you pass to docker build
docker build -t myapp .  # Context is current directory
docker build -t myapp ./src  # Context is ./src directory
  1. Verify the file exists in build context
  2. Check .dockerignore rules
  3. Use correct relative paths
  4. Handle Dockerfile in subdirectory
docker — error
# List files in build context directory
ls -la path/to/file
# Build context is the path you pass to docker build
docker build -t myapp .  # Context is current directory
docker build -t myapp ./src  # Context is ./src directory
COPY failed: file not found in build context or excluded by .dockerignore

What this error means

This error occurs during docker build when the COPY instruction cannot find the specified source file. Docker builds operate within a "build context" - the directory and files sent to the Docker daemon. Files outside this context or excluded by .dockerignore are invisible to the build. The path in COPY is relative to the build context root, not the Dockerfile location. This distinction often causes confusion.

Typical symptoms

  • docker build fails at a COPY or ADD instruction
  • Error shows the specific file that cannot be found
  • File exists locally but Docker cannot find it
  • Build worked before adding .dockerignore
  • Build works when .dockerignore is removed

Common causes

  1. File path is wrong relative to build context
  2. File is excluded by .dockerignore
  3. Build context does not include the file (docker build path issue)
  4. File does not exist at all
  5. Case sensitivity mismatch (Linux is case-sensitive)
  6. Symbolic link points outside build context
  7. File was deleted or moved since last successful build

How to fix "COPY failed: file not found in build context or excluded by .dockerignore"

1Verify the file exists in build context

Check that the file exists where Docker expects it:

bash
# List files in build context directory
ls -la path/to/file

# Build context is the path you pass to docker build
docker build -t myapp .  # Context is current directory
docker build -t myapp ./src  # Context is ./src directory

COPY paths are relative to the context root, not the Dockerfile.

2Check .dockerignore rules

Review your .dockerignore file:

bash
cat .dockerignore

Common patterns that might exclude your file:

bash
# These exclude too much
*
!Dockerfile

# More precise
node_modules
.git
*.log

Test by temporarily removing .dockerignore or commenting out rules.

3Use correct relative paths

Ensure COPY paths are relative to build context:

dockerfile
# If your structure is:
# project/
#   Dockerfile
#   src/
#     app.js
#   package.json

# Correct:
COPY package.json .
COPY src/ ./src/

# Wrong (these look for /src at context root):
COPY ./src/app.js .  # Correct relative path
COPY /src/app.js .   # Wrong - absolute path
4Handle Dockerfile in subdirectory

When Dockerfile is not in the context root:

bash
# Dockerfile at: docker/Dockerfile
# Files at: src/

# Specify Dockerfile location separately
docker build -f docker/Dockerfile -t myapp .

The context is still "." - COPY paths are relative to ".", not to the Dockerfile.

5Check case sensitivity

Linux filesystems are case-sensitive:

dockerfile
# These are different files on Linux:
COPY README.md .
COPY readme.md .

# Check exact filename
ls -la | grep -i readme

Ensure the COPY instruction matches the exact case of the file.

6Debug with build context inspection

See what Docker actually sees:

bash
# Create a tarball of what Docker would send
tar -cvf context.tar --exclude-from=.dockerignore .

# Or use dry-run to check context size
docker build --no-cache --progress=plain -t test . 2>&1 | head -20

Large context size might indicate missing .dockerignore.

Advanced notes

Multi-stage Build Context: In multi-stage builds, COPY --from=builder copies from another stage, not from build context. These have different paths:

dockerfile
COPY --from=builder /app/dist ./dist  # From builder stage
COPY ./config ./config                  # From build context

Symlinks: Symbolic links pointing outside the build context cannot be followed. Either copy the actual files or use bind mounts at runtime.

Git Repositories: If building from a Git URL, only committed files are included: docker build https://github.com/user/repo.git

Frequently asked questions

What does "COPY failed: file not found in build context or excluded by .dockerign" mean?
This error occurs during docker build when the COPY instruction cannot find the specified source file. Docker builds operate within a "build context" - the directory and files sent to the Docker daemon. dockerignore are invisible to the build.
How do I fix "COPY failed: file not found in build context or excluded by .dockerign"?
The file you are trying to COPY does not exist in the build context or is excluded by .dockerignore. Check the file path relative to the Dockerfile and your .dockerignore rules.
What causes "COPY failed: file not found in build context or excluded by .dockerign"?
File path is wrong relative to build context File is excluded by .dockerignore Build context does not include the file (docker build path issue)
Is the "COPY failed: file not found in build context or excluded by .dockerign" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading