Docker Build Failed? Fix Every Common Error

Which error are you seeing?

Fix 1 — COPY failed: file not found in build context

The full error looks like: COPY failed: file not found in build context or excluded by .dockerignore: stat requirements.txt: file does not exist

1. Always run docker build from the repo root

The last argument to docker build is the build context directory. Docker sends that entire directory to the daemon. COPY paths are relative to it — not to where your Dockerfile lives.

# Wrong: building from a subdirectory makes ../app invisible
cd docker/
docker build -t myapp .

# Correct: build from repo root, point -f at the Dockerfile
cd /path/to/repo
docker build -f docker/Dockerfile -t myapp .

2. Add a .dockerignore to exclude large directories

Without a .dockerignore, Docker sends node_modules, .git, and build artifacts to the daemon — slowing every build and sometimes causing COPY conflicts. This file belongs in the same directory as your Dockerfile (or repo root).

# .dockerignore
node_modules
.git
.env
*.log
dist
__pycache__
.pytest_cache
.venv

Fix 2 — Stop pip install from running on every build

Docker processes Dockerfile instructions top-to-bottom and caches each layer. The moment a layer changes, every layer below it rebuilds from scratch. The most common mistake is copying all source code before running the install step.

Bad — copies everything first, busts cache on any file change

FROM python:3.12-slim
WORKDIR /app
COPY . .                          # any src change invalidates this layer
RUN pip install -r requirements.txt  # re-runs every time!

Good — copy manifests first, install, then copy source

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .           # only changes when deps change
RUN pip install --no-cache-dir -r requirements.txt
COPY . .                          # source changes do NOT bust install cache

The same pattern applies to Node.js: copy package.json and package-lock.json, run npm ci, then copy everything else.

Fix 3 — Multistage builds: keep the final image small

A multistage build compiles or installs in a full image, then copies only the output into a slim runtime image. The build tools (compilers, dev dependencies, pip) never appear in the final layer.

# Stage 1: build
FROM node:20 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build          # output goes to /app/dist

# Stage 2: slim runtime (no node_modules, no dev tools)
FROM node:20-slim
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
EXPOSE 3000
CMD ["node", "dist/server.js"]

The AS builder label lets the second stage reference the first with --from=builder. You can have as many stages as needed; only the last one ships.

Fix 4 — exec /bin/sh: exec format error (Apple Silicon)

On M1/M2/M3 Macs, Docker defaults to linux/arm64. Most cloud servers (EC2, GKE, Fly.io) run linux/amd64. The result is a binary that the server cannot execute.

Option A — build for amd64 explicitly (simplest)

docker build --platform linux/amd64 -t myapp:latest .
docker push myapp:latest

Option B — multi-platform manifest with Buildx (CI/CD)

docker buildx create --use
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t myapp:latest \
  --push .

Buildx produces a manifest list: the registry serves the correct image for each architecture automatically. This is the recommended approach for images you push to Docker Hub or GitHub Container Registry.

Fix 5 — ARG vs ENV: build-time vs runtime variables

ARG and ENV look similar but serve different purposes:

ARG NODE_VERSION=20          # only during build
FROM node:{NODE_VERSION}-slim  # uses ARG value

ARG APP_VERSION
ENV APP_VERSION={APP_VERSION}  # promote ARG → ENV so app can read it at runtime
ENV NODE_ENV=production        # always set at runtime

Never put secrets in ENV — they are visible via docker inspect and baked into image layers. Use Docker secrets or a secrets manager at runtime instead.

Fix 6 — Port binding: EXPOSE does nothing by itself

EXPOSE 3000 in a Dockerfile is metadata that documents which port the container listens on. It does not actually open or map the port. Use -p in docker run to map it to the host.

# Maps host port 8080 → container port 3000
docker run -p 8080:3000 myapp

# Bind only on localhost (not exposed to network)
docker run -p 127.0.0.1:3000:3000 myapp

# Let Docker pick a random host port
docker run -p 3000 myapp
docker port myapp  # see what port was assigned

In docker-compose, port mapping is in the ports: section: "8080:3000". The format is always HOST:CONTAINER.

Frequently asked questions

Related guides