Docker

Docker Build Errors: Common Issues and Fixes

Intermediate
11 minutes
Updated October 2026

Troubleshoot common Docker build errors with solutions for cache, networking, and permission issues.

Table of Contents

How to Read a Build Failure

Before jumping to fixes, three habits that cut diagnosis time dramatically:

# 1. Get the full un-collapsed output (BuildKit hides context by default)
docker build --progress=plain -t my-app . 2>&1 | tee build.log

# 2. Find the failing step — the error names a stage like [4/7]
grep -n "ERROR\|error\|failed" build.log

# 3. Re-run just the failing step interactively
docker build --target builder -t my-app-debug .
docker run -it my-app-debug /bin/sh   # reproduce the failing RUN by hand

Most "mysterious" build errors become obvious when you can shell into the layer before the failure and run the command yourself — you see the real stderr, the real filesystem state, and the real environment variables.

Network Errors

Error: "failed to fetch" or "Temporary failure resolving"

failed to fetch http://deb.debian.org/debian/dists/bookworm/InRelease
Temporary failure resolving 'deb.debian.org'

Cause: Container cannot reach package repositories — DNS or network issue.

Solutions:

# 1. Check Docker DNS — add to /etc/docker/daemon.json
{
  "dns": ["8.8.8.8", "8.8.4.4"]
}

# Then restart Docker
sudo systemctl restart docker

# 2. Build with host network
docker build --network=host -t my-app .

# 3. Behind a corporate proxy — pass proxy settings
docker build \
  --build-arg HTTP_PROXY=http://proxy.company.com:8080 \
  --build-arg HTTPS_PROXY=http://proxy.company.com:8080 \
  -t my-app .

Error: "certificate signed by unknown authority"

Cause: Corporate proxy doing TLS inspection, or missing CA certificates.

Solution:

# Copy your corporate CA certificate
COPY corp-ca.crt /usr/local/share/ca-certificates/corp-ca.crt
RUN update-ca-certificates

Permission Errors

Error: "Permission denied" when running commands

/bin/sh: ./script.sh: Permission denied

Solutions:

# Make script executable
COPY script.sh /app/script.sh
RUN chmod +x /app/script.sh
CMD ["/app/script.sh"]

Or fix line endings (Windows CRLF issue):

# Convert to LF line endings
dos2unix script.sh
# or
sed -i 's/\r$//' script.sh

Error: "mkdir: cannot create directory: Permission denied"

Cause: Running as non-root user without write permissions.

# Create directory with correct ownership BEFORE switching user
RUN mkdir -p /app/data && chown -R appuser:appuser /app
USER appuser

Cache Issues

Error: Stale dependencies after code change

Symptom: You changed package.json but npm install used the cache.

# Clear build cache for specific layers
docker build --no-cache -t my-app .

# Or clear all builder cache
docker builder prune -a

Cache not being used efficiently

Problem: Every small code change rebuilds all dependencies.

# Wrong order — cache busted on every code change
COPY . .
RUN npm ci

# Correct order — dependencies cached separately
COPY package.json package-lock.json ./
RUN npm ci
COPY . .

Build Context Errors

Error: "COPY failed: file not found in build context"

COPY failed: file not found in build context or excluded by .dockerignore

Causes and fixes:

# 1. File is outside the build context — build from correct directory
docker build -f docker/Dockerfile .   # build context is '.', not 'docker/'

# 2. File is in .dockerignore — check your .dockerignore file
cat .dockerignore

# 3. Wrong filename case (Linux is case-sensitive)
COPY Config.json .   # fails if file is config.json

Error: Build context too large / slow uploads

Solution: Add a .dockerignore file:

node_modules
.git
.next
dist
coverage
*.log
.env*
Dockerfile
docker-compose.yml

Base Image Errors

Error: "manifest unknown" or "not found"

manifest for node:99 not found: manifest unknown

Cause: The tag doesn't exist.

# Check available tags on Docker Hub
# https://hub.docker.com/_/node/tags

# Or search via API
curl -s "https://registry.hub.docker.com/v2/repositories/library/node/tags?page_size=10" | jq '.results[].name'

Error: "toomanyrequests" from Docker Hub

toomanyrequests: You have reached your pull rate limit

Solutions:

# 1. Login to Docker Hub (increases limits)
docker login

# 2. Use a mirror / pull-through cache
# /etc/docker/daemon.json
{
  "registry-mirrors": ["https://mirror.gcr.io"]
}

# 3. Use alternative registries
FROM public.ecr.aws/docker/library/node:20-alpine

Architecture Errors

Error: "exec format error" at runtime

exec /usr/local/bin/node: exec format error

Cause: Image built for wrong architecture (e.g., arm64 image on amd64 host — common with Apple Silicon Macs deploying to Intel servers).

Solution:

# Build for a specific platform
docker build --platform linux/amd64 -t my-app .

# Or build multi-arch
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t myregistry/my-app:1.0 \
  --push .

Disk Space Errors

Error: "no space left on device"

ERROR: failed to solve: write /var/lib/docker/... : no space left on device

Cause: Docker's data directory (/var/lib/docker) is full — old images, build cache, and stopped containers accumulate silently.

# See what's consuming space
docker system df -v

# Reclaim: stopped containers, dangling images, unused networks, build cache
docker system prune -a          # aggressive — removes ALL unused images

# Just the build cache (usually the biggest chunk)
docker builder prune -a

On CI runners, schedule a periodic prune — a shared runner that builds dozens of images daily fills a 50 GB disk surprisingly fast. The docker system prune in a cron/systemd timer prevents the 2 AM "builds randomly failing" ticket.

Quick Diagnosis Commands

# See detailed build output
docker build --progress=plain -t my-app .

# Build and keep intermediate containers for debugging
docker build --rm=false -t my-app .

# Inspect a failed image's intermediate layer
docker run -it <intermediate-image-id> /bin/sh

# Check disk space (builds fail when disk is full)
docker system df
docker system prune

Error Reference Table

ErrorMost Likely CauseFirst Thing to Try
failed to fetchNetwork/DNS--network=host
Permission deniedMissing exec bit / wrong userchmod +x
file not found in build context.dockerignore or wrong contextCheck .dockerignore
manifest unknownBad tagCheck tag on registry
toomanyrequestsDocker Hub rate limitdocker login
exec format errorWrong architecture--platform linux/amd64
no space left on deviceDisk fulldocker system prune

Prevention Checklist

Most build errors are preventable at the Dockerfile level:

  • Pin base images (node:20.18.0-alpine, not node:latest) — disappearing tags and surprise major bumps cause "manifest unknown" and runtime breakage
  • Order layers for cache — dependency files (package.json, go.mod) copied and installed before source code
  • Keep a .dockerignore — faster context uploads, and node_modules/.git never leak into the image
  • --platform in CI — if your CI runner is arm64 and prod is amd64, set --platform linux/amd64 explicitly or use buildx multi-arch
  • Health-check network steps early — a RUN curl smoke test before the expensive steps fails fast on proxy/DNS issues
  • Prune CI runners — docker builder prune on a schedule before disk errors become your problem
Written & Reviewed by Yasir Masood, CloudOpsGuide Editor

Our tutorials and troubleshooting runbooks are written by a DevOps practitioner with hands-on experience operating Kubernetes, Terraform, CI/CD pipelines, and Linux infrastructure in production. Commands, manifests, and configurations are verified against current tooling releases. Learn more about our editorial process or report a correction or outdated flag.