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

DockerBEGINNERLOWUpdated Dec 6, 2025· 120 views

This error occurs when Docker's ADD or COPY instruction tries to access a file that either doesn't exist in the build context directory, is located outside the context, or is excluded by .dockerignore.

Quick fix

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

docker build -t myapp .
  1. Verify the file exists in the build context directory
  2. Check your .dockerignore file
  3. Specify the correct build context in docker build
  4. Fix the ADD/COPY path in your Dockerfile
docker — error
docker build -t myapp .
ADD failed: file not found in build context or excluded by .dockerignore

What this error means

This error appears during a Docker image build when the ADD (or COPY) instruction in your Dockerfile references a file that the Docker daemon cannot find or access. The build context is the set of files located at the path specified in your docker build command—only files within this context can be added to the image. Docker sends the entire build context to the daemon at the start of the build process. If your ADD instruction references a file outside this context, in a parent directory, or excluded by .dockerignore patterns, the build will fail with this error. Understanding the build context is crucial: it's not just about where your Dockerfile is located, but where you run the docker build command from and what path you specify as the context argument.

Typical symptoms

  • Docker build fails with "ADD failed: file not found in build context or excluded by .dockerignore"
  • Build works locally but fails in CI/CD pipelines with different working directories
  • Error message includes "stat [filename]: file does not exist"
  • Build succeeds when files are moved into the Dockerfile directory

Common causes

  1. The file path in ADD/COPY is outside the build context directory
  2. The file is excluded by patterns in .dockerignore
  3. Incorrect build context specified in docker build command (using "." when files are elsewhere)
  4. Using relative paths like "../file" which go outside the build context
  5. The Dockerfile location differs from the build context, causing path confusion
  6. Trailing comments in COPY/ADD instructions are interpreted as part of the filename
  7. File exists locally but is in .gitignore and missing from the repository in CI

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

1Verify the file exists in the build context directory

First, confirm that the file you're trying to ADD actually exists within your build context. If you're running:

bash
docker build -t myapp .

Then the build context is the current directory (.). List all files to verify:

bash
ls -la

If the file is in a parent directory or elsewhere, you have two options:
1. Move the file into the build context
2. Change the build context to include the file (see next steps)

2Check your .dockerignore file

The .dockerignore file (if it exists) may be excluding your file. Check for patterns that match your file:

bash
cat .dockerignore

Common problematic patterns:
- * (excludes everything)
- *.log (might match your file extension)
- Directory patterns that include your file

To fix, either:
1. Remove the pattern excluding your file
2. Add an exception using ! before the pattern:

dockerignore
# Exclude all logs
*.log
# But include this specific one
!important.log

Note: The last matching line wins, so order matters!

3Specify the correct build context in docker build

If your file is outside the current directory, change the build context. The syntax is:

bash
docker build -t imageName -f /path/to/Dockerfile /path/to/context

Example: If your Dockerfile is in ./docker/ but needs to COPY files from the project root:

bash
# Instead of this (fails):
docker build -t myapp ./docker

# Use this (context is parent directory):
docker build -t myapp -f ./docker/Dockerfile .

For docker-compose, adjust the context in your docker-compose.yml:

yaml
services:
  app:
    build:
      context: ../..  # Go up two directories
      dockerfile: ./project/docker/Dockerfile
4Fix the ADD/COPY path in your Dockerfile

Ensure your ADD/COPY paths are relative to the build context, not the Dockerfile location. You cannot use ../ to go outside the context:

dockerfile
# ❌ WRONG - tries to go outside context
ADD ../config.json /app/

# ✅ CORRECT - relative to context root
ADD config.json /app/

# ✅ CORRECT - file in subdirectory of context
ADD configs/app.json /app/

Also check for trailing comments (they're not ignored!):

dockerfile
# ❌ WRONG - Docker looks for "file.txt # comment"
COPY file.txt /app/ # important file

# ✅ CORRECT
# important file
COPY file.txt /app/
5Verify file permissions and case sensitivity

Ensure Docker can read the file:

bash
# Check file permissions
ls -l yourfile.txt

# Make readable if needed
chmod 644 yourfile.txt

Watch for case sensitivity issues, especially when building on case-insensitive filesystems (macOS/Windows) that deploy to Linux:

dockerfile
# If your file is "Config.json" but you write:
COPY config.json /app/  # This might fail on Linux!

Always match the exact case.

Advanced notes

Build Context Best Practices:
- Keep your build context small—Docker sends the entire context to the daemon, which can be slow for large directories
- Use .dockerignore aggressively to exclude node_modules, .git, and other large directories
- Consider using multi-stage builds to separate build-time and runtime dependencies

Alternative: Using named build contexts (Docker 20.10+):
For complex projects, you can reference files from multiple contexts:

bash
docker build --build-context otherproject=../other/path -t myapp .

Then in your Dockerfile:

dockerfile
FROM alpine
COPY --from=otherproject src/file.txt /app/

CI/CD Considerations:
This error often appears in CI pipelines where the directory structure differs from local development. Always use explicit build context paths in CI scripts, and verify files are committed to git (not just present locally).

Docker Compose Context Gotcha:
In docker-compose.yml, the context path is relative to the compose file location, not your current directory when running docker-compose up.

Frequently asked questions

What does "ADD failed: file not found in build context or excluded by .dockerigno" mean?
This error appears during a Docker image build when the ADD (or COPY) instruction in your Dockerfile references a file that the Docker daemon cannot find or access. The build context is the set of files located at the path specified in your docker build command—only files within this context can be added to the image. Docker sends the entire build context to the daemon at the start of the build process.
How do I fix "ADD failed: file not found in build context or excluded by .dockerigno"?
This error occurs when Docker's ADD or COPY instruction tries to access a file that either doesn't exist in the build context directory, is located outside the context, or is excluded by .dockerignore.
What causes "ADD failed: file not found in build context or excluded by .dockerigno"?
The file path in ADD/COPY is outside the build context directory The file is excluded by patterns in .dockerignore Incorrect build context specified in docker build command (using "." when files are elsewhere)
Is the "ADD failed: file not found in build context or excluded by .dockerigno" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading