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

DockerBEGINNERMEDIUM

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 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.

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.

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

What this error means

Typical symptoms

Common causes

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

Advanced notes

Related errors

Official resources & further reading