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.
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.
First, confirm the file actually exists relative to where you're running 'docker build':
# 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).
The .dockerignore file may be excluding your file. Open .dockerignore and look for patterns matching your file:
# View your .dockerignore
cat .dockerignoreCommon 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:
# Exclude all JSON files
*.json
# But include this specific one
!config.jsonException rules with ! must come AFTER the pattern they're overriding.
COPY paths must be relative to the build context, not the Dockerfile location. If your structure is:
project/
├── docker/
│ └── Dockerfile
├── app/
│ └── main.py
└── config.jsonAnd you build with docker build -f docker/Dockerfile ., your COPY instruction should be:
# 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.
When using the -f flag to specify a Dockerfile in a different location, ensure your build context is set correctly:
# 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.
Docker does not ignore trailing comments in COPY instructions. This will fail:
# Wrong - Docker looks for file named "config.json # important file"
COPY config.json /etc/ # important fileRemove the trailing comment or place it on a separate line:
# Correct - comment on separate line
# Copy important configuration file
COPY config.json /etc/If you're copying a symbolic link that points to a file outside your build context, Docker cannot follow it:
# 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 contextAfter making corrections, rebuild without cache to ensure a clean build:
# Build without using cache
docker build --no-cache -t your-image:tag .
# Or if using docker-compose
docker-compose build --no-cacheThis ensures Docker doesn't use cached layers that might hide the issue.
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.
dockerfile parse error line 5: unknown instruction: RRUN
How to fix 'unknown instruction' Dockerfile parse error in Docker
Error response from daemon: manifest for nginx:nonexistent not found: manifest unknown: manifest unknown
How to fix 'manifest for image:tag not found' in Docker
Error response from daemon: invalid reference format: repository name must be lowercase
How to fix 'repository name must be lowercase' in Docker
Error response from daemon: No such image
How to fix 'No such image' in Docker
Error response from daemon: Container is not running
How to fix 'Container is not running' when using docker exec