How to Fix Docker Build Failed Error

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

The Problem

You run docker build and get:

 => ERROR [3/5] RUN npm install
------
 > [3/5] RUN npm install:
npm ERR! code ENOENT
npm ERR! syscall open
npm ERR! path /app/package.json
npm ERR! errno -2
npm ERR! package.json ENOENT
npm ERR! A complete log of this run can be found in: /root/.npm/_logs/...
------
Dockerfile:5
--------------------
   3 |     WORKDIR /app
   4 |     COPY . .
   5 | >>> RUN npm install
--------------------
ERROR: failed to solve: process "/bin/sh -c npm install" did not complete successfully: exit code: 1

Build failures happen when a Dockerfile instruction returns a non-zero exit code. Common causes: missing files, network timeouts, or invalid syntax.

Quick Fix

Step 1: Read the error layer

Docker prints the failing step number. Look at the layer marked >>>>:

 > [3/5] RUN npm install

This tells you exactly which instruction failed. Check the command and its dependencies.

Step 2: Fix missing files

If package.json is missing, your .dockerignore might be excluding it, or the COPY instruction has the wrong source path:

# Wrong: copies everything from a different directory
COPY ./frontend/package*.json ./

# Right: copy from the build context root
COPY package*.json ./
RUN npm install
COPY . .

Step 3: Retry with no cache

docker build --no-cache -t my-app .

This forces Docker to re-run every step instead of using cached layers, which fixes stale dependency issues.

Step 4: Debug interactively

docker build -t debug --target <stage> .
docker run -it --entrypoint /bin/sh debug

Inside the container, manually run the failing command to see the exact error.

Alternative Solutions

For network timeouts during apt-get or npm install:

# Use a different mirror
RUN npm config set registry https://registry.npmmirror.com
# Or retry with increased timeout
RUN npm install --fetch-retries=5

Inspect Container Configuration

docker inspect <container-id> --format '{{json .Config}}' | python3 -m json.tool
# {
#   "Hostname": "abc123",
#   "Env": ["PATH=/usr/local/bin:..."],
#   "Cmd": ["node", "app.js"]
# }

Use docker inspect to examine the full configuration of a container. This reveals misconfigurations in environment variables, command arguments, and network settings that may not appear in logs.

Additional Troubleshooting

# Check the error message and stack trace for more context
echo "Review the full error output to identify the root cause"

If the above steps do not resolve the issue, examine the complete error message and stack trace. Often the key detail is in the middle of the traceback rather than the final line. Search for the error message in the project documentation or issue tracker for additional solutions.

Prevention

• Add a .dockerignore file to exclude node_modules and .git.
• Pin base image versions (FROM node:18-alpine not FROM node:latest).
• Run docker build with --progress=plain to see full output.