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

DockerBEGINNERMEDIUMUpdated Dec 6, 2025· 262 views

This error occurs when Docker cannot find a file specified in the ADD or COPY instruction. The file either does not exist in the build context directory, is located outside the build context, or has been excluded by a .dockerignore rule.

Quick fix

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

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

# Or find files matching a pattern
find . -name "filename*" -type f
  1. Verify the file exists and check its exact path
  2. Check your .dockerignore file
  3. Verify you're running docker build from the correct directory
  4. Fix path references in Dockerfile
docker — error
# List files in your build context directory
ls -la ./path/to/file
# Or find files matching a pattern
find . -name "filename*" -type f
ADD failed: file not found in build context or excluded by .dockerignore

What this error means

The "ADD failed: file not found in build context or excluded by .dockerignore" error indicates that Docker's build process cannot locate a file you're trying to copy into your image. This happens during the image build phase when Docker processes ADD or COPY instructions in your Dockerfile. The build context is the directory (and its subdirectories) that you specify when running `docker build`. Docker sends this entire context to the Docker daemon before starting the build. The key constraint is that ADD and COPY can only access files within this build context - they cannot reach files outside it, regardless of how you write the path. There are two main causes: either the file genuinely doesn't exist at the specified path relative to the build context, or the file exists but is being filtered out by .dockerignore patterns before Docker even sees it.

Typical symptoms

  • Build fails immediately at ADD or COPY instruction
  • Error message shows the exact filename that cannot be found
  • The file exists on your filesystem but Docker claims it doesn't exist
  • Build works locally but fails in CI/CD pipelines
  • Error appears after modifying .dockerignore or changing build directory

Common causes

  1. File path in Dockerfile is incorrect or contains typos
  2. File is outside the Docker build context directory
  3. File is excluded by a pattern in .dockerignore
  4. Running docker build from the wrong directory
  5. Using absolute paths instead of paths relative to build context
  6. File is a symlink pointing outside the build context
  7. In docker-compose, the context is set incorrectly
  8. File was not committed to version control (CI/CD builds)
  9. Trailing comment in Dockerfile is interpreted as part of the filename

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

1Verify the file exists and check its exact path

First, confirm the file actually exists where you expect it:

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

# Or find files matching a pattern
find . -name "filename*" -type f

Check for typos in both the filename and the path. Paths in Docker are case-sensitive, even on Windows/macOS.

Compare the path in your Dockerfile with the actual file location:

dockerfile
# If your Dockerfile says:
COPY src/config.json /app/

# Then this file must exist:
# ./src/config.json (relative to build context)
2Check your .dockerignore file

If the file exists but Docker can't see it, check if .dockerignore is excluding it:

bash
# View your .dockerignore
cat .dockerignore

Common problematic patterns:

text
# These patterns might accidentally exclude your file:
*           # Excludes everything!
*.json      # Excludes all JSON files
src/        # Excludes entire src directory
**/*.config # Excludes all .config files in any directory

To fix, either remove the offending pattern or add a negation rule. Order matters - negations must come after the exclusion:

text
# Exclude all, then re-include specific files
*
!src/
!src/**
!package.json
!Dockerfile

Tip: Temporarily rename .dockerignore to test if it's the cause:

bash
mv .dockerignore .dockerignore.bak
docker build -t test .
mv .dockerignore.bak .dockerignore
3Verify you're running docker build from the correct directory

The build context is determined by where you run the docker build command. Ensure you're in the right directory:

bash
# Check current directory
pwd

# The '.' at the end sets the build context to current directory
docker build -t myimage .

If your Dockerfile is in a subdirectory, you have two options:

Option A: Run from parent directory with -f flag:

bash
# From project root
docker build -f docker/Dockerfile -t myimage .

Option B: Run from the Dockerfile's directory:

bash
cd docker
docker build -t myimage .
# Note: Now COPY paths must be relative to docker/ directory

For CI/CD pipelines, explicitly set the working directory before building.

4Fix path references in Dockerfile

COPY and ADD paths must be relative to the build context, not absolute or relative to Dockerfile location.

Wrong - absolute path:

dockerfile
COPY /home/user/myapp/config.json /app/  # Will look for ./home/user/myapp/config.json

Wrong - parent directory:

dockerfile
COPY ../shared/utils.js /app/  # Cannot access parent of build context

Correct - relative to build context:

dockerfile
COPY config.json /app/
COPY src/ /app/src/

If you need files from outside the build context, you have two options:

1. Expand the build context:

bash
# Run from parent directory that contains both folders
cd ..
docker build -f app/Dockerfile -t myimage .

2. Copy files into build context before building:

bash
cp ../shared/utils.js ./lib/
docker build -t myimage .
5Fix docker-compose context configuration

In docker-compose.yml, the context determines the build context directory. Common mistakes:

Problem: Context doesn't include required files:

yaml
services:
  app:
    build:
      context: ./app          # Only ./app/ is sent to Docker
      dockerfile: Dockerfile

Solution A: Expand context to parent:

yaml
services:
  app:
    build:
      context: .              # Entire project is the context
      dockerfile: app/Dockerfile

Solution B: Restructure to keep files in context:

yaml
services:
  app:
    build:
      context: ./app
      dockerfile: Dockerfile
    # Ensure all COPY sources exist within ./app/

After changing context, update COPY paths in Dockerfile to match:

dockerfile
# If context is now project root instead of ./app:
COPY app/src/ /app/src/     # Was: COPY src/ /app/src/
COPY shared/ /app/shared/   # Now accessible
6Check for symlinks pointing outside build context

Symlinks that point to files outside the build context will fail:

bash
# Check if file is a symlink
ls -la config.json
# lrwxrwxrwx config.json -> /etc/myapp/config.json  # This won't work!

Docker follows symlinks, but the target must be within the build context.

Fix: Replace symlink with actual file:

bash
# Remove symlink and copy actual file
rm config.json
cp /etc/myapp/config.json ./config.json

Or use a build argument to inject the content:

dockerfile
ARG CONFIG_CONTENT
RUN echo "$CONFIG_CONTENT" > /app/config.json
bash
docker build --build-arg CONFIG_CONTENT="$(cat /etc/myapp/config.json)" -t myimage .
7Remove trailing comments from COPY/ADD lines

Docker does not support trailing comments on the same line as COPY or ADD instructions. They get interpreted as part of the filename:

Wrong:

dockerfile
COPY config.json /app/  # Important config file
# Docker looks for file named "config.json /app/ # Important config file"

Correct:

dockerfile
# Important config file
COPY config.json /app/

This is a common gotcha for developers coming from languages where trailing comments are standard.

Advanced notes

Understanding build context transfer: When you run docker build, the CLI packages the entire build context into a tarball and sends it to the Docker daemon. This happens before any Dockerfile instructions run. Use docker build output to see context size:

bash
Sending build context to Docker daemon  45.2MB

If this is unexpectedly large or small, it indicates context issues.

BuildKit and .dockerignore: With BuildKit (default in Docker 20.10+), you can use .dockerignore patterns more efficiently. BuildKit only transfers files that are actually referenced in COPY/ADD instructions, making large exclusion lists less critical for performance.

Multi-stage builds and context: In multi-stage builds, COPY --from copies from another stage, not the build context:

dockerfile
FROM golang:1.21 AS builder
COPY . .
RUN go build -o /app

FROM alpine
COPY --from=builder /app /app  # From builder stage, not build context
COPY config.json /etc/         # From build context

Debugging context contents: To see exactly what Docker receives, create a Dockerfile that lists the context:

dockerfile
FROM busybox
COPY . /context
RUN find /context -type f

Remote build contexts: Docker supports building from Git URLs or tarballs:

bash
docker build https://github.com/user/repo.git#main:docker

When using remote contexts, local .dockerignore doesn't apply - use .dockerignore committed to the repo.

Heredoc syntax (BuildKit): For small config files, consider inline content to avoid COPY issues:

dockerfile
# syntax=docker/dockerfile:1
COPY <<EOF /app/config.json
{"key": "value"}
EOF

Frequently asked questions

What does "ADD failed: file not found in build context or excluded by .dockerigno" mean?
dockerignore" error indicates that Docker's build process cannot locate a file you're trying to copy into your image. This happens during the image build phase when Docker processes ADD or COPY instructions in your Dockerfile. The build context is the directory (and its subdirectories) that you specify when running docker build.
How do I fix "ADD failed: file not found in build context or excluded by .dockerigno"?
This error occurs when Docker cannot find a file specified in the ADD or COPY instruction. The file either does not exist in the build context directory, is located outside the build context, or has been excluded by a .dockerignore rule.
What causes "ADD failed: file not found in build context or excluded by .dockerigno"?
File path in Dockerfile is incorrect or contains typos File is outside the Docker build context directory File is excluded by a pattern in .dockerignore
Is the "ADD failed: file not found in build context or excluded by .dockerigno" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading