How to Fix Docker Multi-Stage Build Error

In this tutorial, you'll learn about How to Fix Docker Multi. We cover key concepts, practical examples, and best practices.

You try to use multi-stage builds and get COPY --from=... failed or the final image is still too large — stages are not properly named, artifacts are in the wrong paths, or unnecessary files are included.

The Problem

COPY failed: stat /app/build: file does not exist

Or the final image is 2GB even though you used multiple stages.

Step-by-Step Fix

Step 1: Name your build stages

# WRONG — unnamed stages
FROM node:18 AS build
RUN npm run build

FROM nginx:alpine
COPY --from=0 /app/build /usr/share/nginx/html

# RIGHT — named stages
FROM node:18 AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html

Step 2: Verify the build artifact path

Build and test the artifact:

docker build --target build -t temp-builder .
docker run --rm temp-builder ls /app/dist

If files are not there, check your build tool's output directory.

Step 3: Use the correct --from syntax

# WRONG — wrong stage reference
COPY --from=0 /build /app

# RIGHT — use AS names
COPY --from=build /app/dist /usr/share/nginx/html

Step 4: Copy only what is needed

# WRONG — copies everything including node_modules
COPY --from=build /app /app

# RIGHT — copy only the runtime artifact
COPY --from=build /app/dist /usr/share/nginx/html
COPY --from=build /app/package.json /app/

Step 5: Use different base images per stage

# Build stage with full toolchain
FROM node:18 AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Production stage with minimal runtime
FROM node:18-alpine AS production
WORKDIR /app
COPY --from=build /app/dist ./dist
COPY --from=build /app/package.json ./
RUN npm ci --only=production
CMD ["node", "dist/server.js"]

Step 6: Build with target for debugging

docker build --target build -t myapp-builder .

Prevention Tips

• Name all stages with AS keywords
• Build intermediate stages separately during development
• Use .dockerignore to exclude unnecessary files
• Check artifact paths before referencing in COPY --from
• Use docker history to inspect image layers

Common Mistakes with multi stage

1. Using head and tail instead of pattern matching, causing runtime errors on empty lists
2. Forgetting that lazy evaluation defers computation until the value is forced, causing space leaks with unevaluated thunks
3. Using return to exit a function early instead of wrapping a pure value in the monad

These mistakes appear frequently in real-world DOCKER code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ