Docker Build Errors: Common Issues and Fixes
Troubleshoot common Docker build errors with solutions for cache, networking, and permission issues.
Table of Contents
- How to Read a Build Failure
- Network Errors
- Permission Errors
- Cache Issues
- Build Context Errors
- Base Image Errors
- Architecture Errors
- Disk Space Errors
- Quick Diagnosis Commands
- Error Reference Table
- Prevention Checklist
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
| Error | Most Likely Cause | First Thing to Try |
|---|---|---|
failed to fetch | Network/DNS | --network=host |
Permission denied | Missing exec bit / wrong user | chmod +x |
file not found in build context | .dockerignore or wrong context | Check .dockerignore |
manifest unknown | Bad tag | Check tag on registry |
toomanyrequests | Docker Hub rate limit | docker login |
exec format error | Wrong architecture | --platform linux/amd64 |
no space left on device | Disk full | docker system prune |
Prevention Checklist
Most build errors are preventable at the Dockerfile level:
- Pin base images (
node:20.18.0-alpine, notnode: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, andnode_modules/.gitnever leak into the image --platformin CI — if your CI runner is arm64 and prod is amd64, set--platform linux/amd64explicitly or use buildx multi-arch- Health-check network steps early — a
RUN curlsmoke test before the expensive steps fails fast on proxy/DNS issues - Prune CI runners —
docker builder pruneon a schedule before disk errors become your problem
Related Articles
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.