Docker Build Errors: Common Issues and Fixes

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

Table of Contents

• Network Errors
• Permission Errors
• Cache Issues
• Build Context Errors
• Base Image Errors
• Architecture Errors

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 .

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

Related Articles

• Dockerfile Examples: Best Practices
• Docker Security: Scanning and Hardening

---

Last Updated: October 2026
Author: CloudOpsGuide Team
Difficulty: Intermediate
Estimated Reading Time: 11 minutes