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.
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.
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.
# 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).
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.
# View .dockerignore contents
cat .dockerignore
# Look for patterns like:
# */build*
# */*/build*
# **/distIf your files are being excluded, either remove the exclusion pattern or adjust your COPY path to reference files that aren't ignored.
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.
# 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 .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.
# 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 ./Docker's COPY command doesn't support bracket notation when using ARG variables. Use the standard syntax instead.
ARG PROJECT_PATH="./app"
# WRONG: Bracket syntax with variables
# COPY ["${PROJECT_PATH}/dist", "/app/"]
# CORRECT: Standard syntax
COPY ${PROJECT_PATH}/dist /app/When copying multiple files, ensure the destination path ends with a trailing slash to indicate it's a directory.
# 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/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:
RUN ls -la /
RUN ls -la /path/to/expected/filesThis 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.
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