Fix Docker Build Failures When Using Claude Code

The Problem

You ask Claude Code to build your Docker image and it fails:

ERROR [build 4/7] RUN npm ci
#8 12.45 npm ERR! code ENOENT
#8 12.45 npm ERR! syscall open
#8 12.45 npm ERR! path /app/package.json
ERROR: failed to solve: exit code: 1

Quick Fix

The most common causes:

# Wrong: COPY before WORKDIR
COPY package*.json ./
WORKDIR /app  # package.json is now in / not /app

# Right: WORKDIR first, then COPY
WORKDIR /app
COPY package*.json ./
RUN npm ci

What Is Happening

Docker builds execute instructions sequentially in an isolated environment. Each instruction creates a new layer. Common failure points include:

1. Build context issues: Files excluded by .dockerignore or not in the build context directory
2. Layer ordering: Instructions depend on files that have not been copied yet
3. Platform mismatch: Building for linux/amd64 on an ARM Mac (Apple Silicon)
4. Dependency installation: Native modules that need build tools not present in the image
5. Multi-stage references: Incorrect --from references in multi-stage builds

Step-by-Step Fix

Step 1: Read the full error output

docker build --no-cache --progress=plain -t myapp . 2>&1

Step 2: Fix .dockerignore conflicts

A common issue is .dockerignore excluding files needed during the build. Use a targeted ignore list:

node_modules
.git
.env
.env.local
dist
coverage
.next

Step 3: Fix a broken Dockerfile

A well-structured Node.js Dockerfile:

FROM node:20-slim AS builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --ignore-scripts
COPY tsconfig.json ./
COPY src/ ./src/
RUN npm run build

FROM node:20-slim AS production
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev --ignore-scripts && npm cache clean --force
COPY --from=builder /app/dist ./dist
RUN groupadd -r app && useradd -r -g app app
USER app
EXPOSE 3000
CMD ["node", "dist/index.js"]

Step 4: Fix platform/architecture issues

On Apple Silicon Macs:

docker build --platform linux/amd64 -t myapp .

Step 5: Fix layer caching issues

# Bad: copying everything invalidates the npm ci cache
COPY . .
RUN npm ci

# Good: copy dependency files first, install, then copy source
COPY package.json package-lock.json ./
RUN npm ci
COPY . .

Prevention

Add Dockerfile linting to your CI pipeline:

brew install hadolint
hadolint Dockerfile