How to fix COPY failed: no source files were specified in Docker

DockerBEGINNERLOWUpdated Dec 6, 2025· 162 views

This error occurs when Docker cannot find the files specified in a COPY instruction during image build. It typically happens due to incorrect build context, .dockerignore rules, or multi-stage build configuration issues.

Quick fix

Fixes COPY failed: no source files were specified

# List files in your build context
ls -la ./app/dist

# Run docker build with context path
docker build -t myimage:latest .
  1. Verify source files exist in build context
  2. Check .dockerignore file for exclusions
  3. Avoid copying files outside build context
  4. Fix multi-stage build COPY commands
docker — error
# List files in your build context
ls -la ./app/dist
# Run docker build with context path
docker build -t myimage:latest .
COPY failed: no source files were specified

What this error means

The "COPY failed: no source files were specified" error appears when Docker's build process cannot locate files referenced in a COPY instruction within your Dockerfile. Docker builds images using a "build context" - the set of files from the directory you specify (usually the current directory with `.`). When a COPY command references files that don't exist in this context, are excluded by .dockerignore rules, or are inaccessible due to multi-stage build limitations, Docker cannot proceed and throws this error. This error is Docker's way of preventing builds from continuing when required files are missing, which would result in incomplete or broken container images. Understanding the build context and how Docker resolves file paths is key to resolving this issue.

Typical symptoms

  • Docker build fails during COPY instruction execution
  • Error message specifically mentions 'no source files were specified'
  • Build works locally but fails in CI/CD pipelines
  • Multi-stage builds fail when copying from previous stages
  • COPY commands with wildcards don't match any files

Common causes

  1. Source files or directories don't exist in the build context
  2. Files are excluded by .dockerignore patterns
  3. Attempting to copy files outside the build context (e.g., ../parent/file)
  4. Multi-stage build copying from wrong stage or non-existent path
  5. Using bracket syntax with ARG variables (e.g., COPY [${var}, "./"])
  6. Source directory is a symbolic link pointing outside the build context
  7. Case sensitivity issues on case-sensitive file systems
  8. Missing trailing slash when copying multiple files to a directory

How to fix "COPY failed: no source files were specified"

1Verify source files exist in build context

First, confirm the files you're trying to copy actually exist relative to your build context. If your Dockerfile contains COPY ./app/dist /app, check that the app/dist directory exists in the same directory where you run docker build.

bash
# List files in your build context
ls -la ./app/dist

# Run docker build with context path
docker build -t myimage:latest .

Remember: the build context is the path specified at the end of the docker build command (the . in the example above).

2Check .dockerignore file for exclusions

A .dockerignore file in your project root can exclude files from the build context, even if they physically exist. Review this file for patterns that might be excluding your source files.

bash
# View .dockerignore contents
cat .dockerignore

# Look for patterns like:
# */build*
# */*/build*
# **/dist

If your files are being excluded, either remove the exclusion pattern or adjust your COPY path to reference files that aren't ignored.

3Avoid copying files outside build context

Docker cannot access files outside the build context for security reasons. If you need to copy files from parent directories, restructure your project or change the build context.

dockerfile
# This will FAIL - outside build context
COPY ../config/app.json /app/

# Solution 1: Change build context to parent directory
# docker build -t myimage:latest -f path/to/Dockerfile ..

# Solution 2: Move files into build context before building
# cp ../config/app.json ./config/
# docker build -t myimage:latest .
4Fix multi-stage build COPY commands

In multi-stage builds, files created in one stage aren't automatically available in subsequent stages. Use the --from flag to copy from a previous stage.

dockerfile
# Stage 1: Build
FROM node:18 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

# Stage 2: Production
FROM node:18-slim
WORKDIR /app

# WRONG: This will fail
# COPY /app/dist ./dist

# CORRECT: Copy from the builder stage
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/package*.json ./
5Remove bracket syntax when using ARG variables

Docker's COPY command doesn't support bracket notation when using ARG variables. Use the standard syntax instead.

dockerfile
ARG PROJECT_PATH="./app"

# WRONG: Bracket syntax with variables
# COPY ["${PROJECT_PATH}/dist", "/app/"]

# CORRECT: Standard syntax
COPY ${PROJECT_PATH}/dist /app/
6Add trailing slash for directory destinations

When copying multiple files, ensure the destination path ends with a trailing slash to indicate it's a directory.

dockerfile
# Copying multiple files - destination must end with /
COPY file1.txt file2.txt config.json /app/config/

# Single file - trailing slash optional but recommended for directories
COPY package.json /app/

Advanced notes

Symbolic Links and Build Context: If your source directory is a symbolic link (symlink) pointing to a location outside the build context, Docker cannot follow it. Replace symlinks with actual files or adjust your build context to include the symlink target.

Case Sensitivity: On case-sensitive file systems (Linux, macOS with APFS case-sensitive), ensure your COPY paths exactly match the actual file names. COPY App.js will fail if the file is actually named app.js.

Docker Build Context Size: Large build contexts can slow down builds. Use .dockerignore to exclude unnecessary files like node_modules, .git, and build artifacts. However, be careful not to exclude files you actually need to COPY.

Debugging Build Context: To see exactly what Docker receives as the build context, you can temporarily add a step to list files:

dockerfile
RUN ls -la /
RUN ls -la /path/to/expected/files

This helps identify whether files are missing from the context or just in an unexpected location.

BuildKit Cache: If you're using Docker BuildKit (enabled by default in recent versions), be aware that aggressive caching might mask issues. Use docker build --no-cache to rule out cache-related problems when debugging.

Frequently asked questions

What does "COPY failed: no source files were specified" mean?
The "COPY failed: no source files were specified" error appears when Docker's build process cannot locate files referenced in a COPY instruction within your Dockerfile. ). dockerignore rules, or are inaccessible due to multi-stage build limitations, Docker cannot proceed and throws this error.
How do I fix "COPY failed: no source files were specified"?
This error occurs when Docker cannot find the files specified in a COPY instruction during image build. It typically happens due to incorrect build context, .dockerignore rules, or multi-stage build configuration issues.
What causes "COPY failed: no source files were specified"?
Source files or directories don't exist in the build context Files are excluded by .dockerignore patterns Attempting to copy files outside the build context (e.g., ../parent/file)
Is the "COPY failed: no source files were specified" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading