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

DockerBEGINNERLOWUpdated Dec 1, 2025· 178 views

This error occurs when Docker cannot locate a file or directory you're trying to copy during the build process. The file may be outside the build context, excluded by .dockerignore, or the path may be incorrect.

Quick fix

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

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

# Or check the entire build context structure
tree .
  1. Verify the file exists in your build context
  2. Check your .dockerignore file
  3. Use correct relative paths in COPY instructions
  4. Specify the correct build context directory
docker — error
# List files in your build context
ls -la path/to/file
# Or check the entire build context structure
tree .
COPY failed: file not found in build context or excluded by .dockerignore

What this error means

The "COPY failed: file not found in build context" error means that Docker's build process cannot access the file or directory you've specified in a COPY instruction. Docker builds operate within a specific build context—typically the directory you specify when running 'docker build'. Any files outside this context are invisible to Docker. This error commonly appears when the Docker daemon receives your build context but cannot find the requested file within it. The error message explicitly states two possible reasons: either the file genuinely doesn't exist in the build context, or it's being filtered out by patterns in your .dockerignore file. Understanding Docker's build context is crucial: when you run 'docker build .', the dot (.) represents your build context directory. Docker packages up all files in this directory and sends them to the Docker daemon, which then processes your Dockerfile instructions.

Typical symptoms

  • Build fails with 'COPY failed: file not found in build context or excluded by .dockerignore'
  • Error message shows 'stat <filename>: file does not exist'
  • Build succeeds locally but fails in CI/CD pipelines
  • Previously working Dockerfile suddenly fails after restructuring project files
  • COPY instruction works for some files but not others

Common causes

  1. File or directory is located outside the Docker build context directory
  2. File path is excluded by a pattern in the .dockerignore file
  3. Incorrect relative path in COPY instruction (relative to build context, not Dockerfile location)
  4. Using absolute paths which Docker interprets relative to build context
  5. Trailing comments in COPY instruction are treated as part of the path
  6. Symbolic links pointing to files outside the build context
  7. Wrong build context specified when using docker build -f flag
  8. Building from STDIN without providing a context directory
  9. File was generated in a previous build step but isn't in the context

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

1Verify the file exists in your build context

First, confirm the file actually exists relative to where you're running 'docker build':

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

# Or check the entire build context structure
tree .

The file must exist in the directory you're building from (usually the directory containing your Dockerfile).

2Check your .dockerignore file

The .dockerignore file may be excluding your file. Open .dockerignore and look for patterns matching your file:

bash
# View your .dockerignore
cat .dockerignore

Common problematic patterns:
- **/*.json excludes all JSON files
- dist/ excludes the entire dist directory
- *.log excludes all log files

To fix, either remove the excluding pattern or add an exception before it:

dockerignore
# Exclude all JSON files
*.json
# But include this specific one
!config.json

Exception rules with ! must come AFTER the pattern they're overriding.

3Use correct relative paths in COPY instructions

COPY paths must be relative to the build context, not the Dockerfile location. If your structure is:

bash
project/
├── docker/
│   └── Dockerfile
├── app/
│   └── main.py
└── config.json

And you build with docker build -f docker/Dockerfile ., your COPY instruction should be:

dockerfile
# Correct - relative to build context (project/)
COPY app/main.py /app/
COPY config.json /etc/

# Wrong - tries to find docker/app/main.py
COPY ../app/main.py /app/

Never use ../ in COPY instructions—it won't work because you cannot access files outside the build context.

4Specify the correct build context directory

When using the -f flag to specify a Dockerfile in a different location, ensure your build context is set correctly:

bash
# Wrong - build context is docker/ directory
docker build -f docker/Dockerfile docker/

# Correct - build context is current directory
docker build -f docker/Dockerfile .

# Correct - build context is app/ directory
docker build -f docker/Dockerfile app/

The last argument to docker build is your build context. All COPY paths are resolved relative to this directory.

5Remove trailing comments from COPY instructions

Docker does not ignore trailing comments in COPY instructions. This will fail:

dockerfile
# Wrong - Docker looks for file named "config.json # important file"
COPY config.json /etc/ # important file

Remove the trailing comment or place it on a separate line:

dockerfile
# Correct - comment on separate line
# Copy important configuration file
COPY config.json /etc/
6Avoid symbolic links to files outside build context

If you're copying a symbolic link that points to a file outside your build context, Docker cannot follow it:

bash
# Check if file is a symbolic link
ls -la path/to/file

# If it's a symlink, either:
# 1. Copy the actual file into your build context
cp /actual/location/file ./

# 2. Or add the target directory to your build context
7Rebuild after fixing the issue

After making corrections, rebuild without cache to ensure a clean build:

bash
# Build without using cache
docker build --no-cache -t your-image:tag .

# Or if using docker-compose
docker-compose build --no-cache

This ensures Docker doesn't use cached layers that might hide the issue.

Advanced notes

Build Context Performance: Large build contexts slow down builds significantly because Docker must send the entire context to the daemon. Use .dockerignore liberally to exclude unnecessary files (node_modules, .git, test files, documentation, etc.). You can inspect what's being sent with 'docker build --progress=plain .' and watching the 'sending build context' step.

Multi-stage Builds: When using multi-stage builds, remember each stage has access to the same build context. However, files created in one stage (e.g., compiled artifacts) are NOT automatically available in subsequent stages—you must explicitly COPY them using the '--from' flag.

CI/CD Considerations: In CI/CD pipelines, the working directory may differ from local development. Always use explicit build context paths and verify that CI clones the full repository or the necessary subdirectories. GitHub Actions, GitLab CI, and other platforms may checkout code into different paths.

Docker Buildx and BuildKit: Modern Docker uses BuildKit by default, which provides better error messages and shows exactly which file it's looking for. Enable BuildKit explicitly with 'DOCKER_BUILDKIT=1 docker build .' if you're using an older Docker version.

Absolute Paths Are Relative: While you might use absolute paths like 'COPY /app/config.json /etc/', Docker interprets this relative to the build context. If your build context is '/home/user/project', it looks for '/home/user/project/app/config.json', NOT '/app/config.json' on your system. This behavior confuses developers coming from traditional shell scripting.

Frequently asked questions

What does "COPY failed: file not found in build context or excluded by .dockerign" mean?
The "COPY failed: file not found in build context" error means that Docker's build process cannot access the file or directory you've specified in a COPY instruction. Docker builds operate within a specific build context—typically the directory you specify when running 'docker build'. Any files outside this context are invisible to Docker.
How do I fix "COPY failed: file not found in build context or excluded by .dockerign"?
This error occurs when Docker cannot locate a file or directory you're trying to copy during the build process. The file may be outside the build context, excluded by .dockerignore, or the path may be incorrect.
What causes "COPY failed: file not found in build context or excluded by .dockerign"?
File or directory is located outside the Docker build context directory File path is excluded by a pattern in the .dockerignore file Incorrect relative path in COPY instruction (relative to build context, not Dockerfile location)
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