DevSecOps

Docker Build Failures: Common Errors and How to Fix Them

DeviDevs Team
••7 min read
#docker#containers#troubleshooting#devops#dockerfile

Docker builds can fail in mysterious ways. This guide covers the most common build failures and provides tested solutions.

Error: Failed to Compute Cache Key

Symptom:

failed to compute cache key: failed to calculate checksum of ref:
"/path/to/file" not found

COPY failed: file not found in build context: requirements.txt

Cause 1: File not in build context

# ❌ File outside context
COPY ../config/app.conf /app/
 
# ✅ Move file into build context or adjust context
docker build -f docker/Dockerfile -t myapp ..

Cause 2: .dockerignore excluding needed files

# Check .dockerignore
cat .dockerignore
 
# Common mistake - ignoring everything then forgetting exceptions
# .dockerignore:
*
!src/
!package.json
!requirements.txt  # Add this if missing

Cause 3: Case sensitivity (Linux vs macOS)

# ❌ Wrong case (works on macOS, fails on Linux)
COPY Requirements.txt /app/
 
# ✅ Exact case match
COPY requirements.txt /app/

Debug - list build context:

# See what's actually in the context
docker build -t test . 2>&1 | head -20
 
# Or use buildx debug
BUILDKIT_PROGRESS=plain docker build -t test .

Error: apt-get Install Failed

Symptom:

E: Unable to locate package some-package
E: Package 'python3' has no installation candidate
Reading package lists... Error!

Solution 1 - Update before install:

# ❌ Missing update
RUN apt-get install -y curl
 
# ✅ Always update first
RUN apt-get update && apt-get install -y \
    curl \
    wget \
    && rm -rf /var/lib/apt/lists/*

Solution 2 - Pin package versions:

# For reproducible builds
RUN apt-get update && apt-get install -y \
    curl=7.88.1-10+deb12u1 \
    && rm -rf /var/lib/apt/lists/*
 
# Or use --no-install-recommends
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl \
    && rm -rf /var/lib/apt/lists/*

Solution 3 - Use different base image:

# If package not available in slim
FROM python:3.12  # Full image instead of python:3.12-slim
 
# Or use Alpine
FROM python:3.12-alpine
RUN apk add --no-cache curl

Error: COPY --from Stage Not Found

Symptom:

failed to solve: failed to compute cache key: "builder" not found
invalid from flag value builder: pull access denied

Cause: Stage name mismatch

# ❌ Wrong stage name
FROM node:20 AS build
RUN npm install && npm run build
 
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html  # 'builder' doesn't exist!
 
# ✅ Correct stage name
FROM node:20 AS builder
RUN npm install && npm run build
 
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html

Check stage exists:

# Debug multi-stage builds
docker build --target builder -t test-builder .
docker run --rm test-builder ls -la /app/

Error: Permission Denied During Build

Symptom:

permission denied while trying to connect to Docker daemon
COPY failed: permission denied
npm ERR! Error: EACCES: permission denied

Solution 1 - Fix file permissions before COPY:

# On host before build
chmod +x scripts/entrypoint.sh
# In Dockerfile
COPY --chmod=755 scripts/entrypoint.sh /app/

Solution 2 - Run as correct user:

# Create non-root user
RUN useradd -m -u 1000 appuser
 
# Set ownership
COPY --chown=appuser:appuser . /app/
 
# Switch to user
USER appuser
 
# npm/pip will work in user space
RUN npm install

Solution 3 - Fix npm permissions:

FROM node:20
 
WORKDIR /app
 
# Create node_modules with correct permissions
RUN mkdir -p /app/node_modules && chown -R node:node /app
 
USER node
 
COPY --chown=node:node package*.json ./
RUN npm ci
 
COPY --chown=node:node . .
RUN npm run build

Error: Out of Memory / Disk Space

Symptom:

no space left on device
Error response from daemon: write /var/lib/docker/tmp/...: no space left
failed to register layer: Error processing tar file: write: no space left

Solution 1 - Clean Docker system:

# Remove all unused data
docker system prune -a
 
# More aggressive cleanup
docker system prune -a --volumes
 
# Check disk usage
docker system df

Solution 2 - Reduce image size:

# ❌ Large image
FROM python:3.12
COPY . /app
RUN pip install -r requirements.txt
 
# ✅ Multi-stage + slim base
FROM python:3.12 AS builder
COPY requirements.txt .
RUN pip install --user -r requirements.txt
 
FROM python:3.12-slim
COPY --from=builder /root/.local /root/.local
COPY . /app
ENV PATH=/root/.local/bin:$PATH

Solution 3 - Optimize layer caching:

# ❌ Invalidates cache on any code change
COPY . /app
RUN npm install
 
# ✅ Dependencies cached separately
COPY package*.json ./
RUN npm ci
COPY . /app
RUN npm run build

Error: Network Timeout During Build

Symptom:

Get "https://registry-1.docker.io/v2/": net/http: request canceled
failed to fetch https://deb.debian.org/...: Connection timed out
pip install timeout

Solution 1 - Configure DNS:

# Docker daemon config (/etc/docker/daemon.json)
{
  "dns": ["8.8.8.8", "8.8.4.4"]
}
 
# Restart Docker
sudo systemctl restart docker

Solution 2 - Use mirrors:

# Use regional npm mirror
RUN npm config set registry https://registry.npmmirror.com && npm install
 
# Use pip mirror
RUN pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt
 
# Use apt mirror
RUN sed -i 's/deb.debian.org/mirrors.ustc.edu.cn/g' /etc/apt/sources.list

Solution 3 - Build with longer timeout:

# Increase timeout for slow connections
DOCKER_BUILDKIT=1 docker build \
  --network=host \
  --build-arg PIP_DEFAULT_TIMEOUT=100 \
  -t myapp .

Error: BuildKit Syntax Errors

Symptom:

failed to solve with frontend dockerfile.v0
failed to create LLB definition: dockerfile parse error

Cause 1: Wrong syntax directive:

# ❌ Syntax directive must be first line
FROM node:20
# syntax=docker/dockerfile:1
 
# ✅ Correct position
# syntax=docker/dockerfile:1
FROM node:20

Cause 2: BuildKit features without enabling:

# Features that require BuildKit
RUN --mount=type=cache,target=/root/.cache pip install -r requirements.txt
RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret
# Enable BuildKit
export DOCKER_BUILDKIT=1
docker build -t myapp .
 
# Or use docker buildx
docker buildx build -t myapp .

Error: Executable Format Error

Symptom:

exec format error
standard_init_linux.go:228: exec user process caused "exec format error"

Cause: Architecture mismatch (ARM vs x86)

# Building for different architecture
# On Mac M1/M2, building for x86:
docker build --platform linux/amd64 -t myapp .
 
# Multi-architecture build
docker buildx build --platform linux/amd64,linux/arm64 -t myapp .

Check image architecture:

docker inspect myapp | grep Architecture

Error: Base Image Pull Failed

Symptom:

pull access denied for myregistry.com/base-image
Error response from daemon: manifest for image:tag not found

Solution 1 - Docker login:

# Login to registry
docker login myregistry.com
 
# Or use credential helper
echo '{"credsStore": "desktop"}' > ~/.docker/config.json

Solution 2 - Check image exists:

# Verify image and tag
docker manifest inspect myregistry.com/base-image:tag
 
# List available tags
curl -s https://registry.hub.docker.com/v2/repositories/library/python/tags/ | jq '.results[].name'

Dockerfile Best Practices

# syntax=docker/dockerfile:1
FROM python:3.12-slim AS builder
 
# Install build dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc \
    && rm -rf /var/lib/apt/lists/*
 
WORKDIR /app
 
# Install Python dependencies
COPY requirements.txt .
RUN --mount=type=cache,target=/root/.cache \
    pip install --user -r requirements.txt
 
# Production stage
FROM python:3.12-slim
 
# Create non-root user
RUN useradd -m -u 1000 appuser
 
WORKDIR /app
 
# Copy dependencies from builder
COPY --from=builder /root/.local /home/appuser/.local
 
# Copy application
COPY --chown=appuser:appuser . .
 
USER appuser
ENV PATH=/home/appuser/.local/bin:$PATH
 
EXPOSE 8000
CMD ["python", "-m", "uvicorn", "main:app", "--host", "0.0.0.0"]

Quick Reference: Build Debug Commands

| Issue | Command | |-------|---------| | Build context check | docker build -t test . 2>&1 \| head | | Verbose build | BUILDKIT_PROGRESS=plain docker build . | | No cache | docker build --no-cache -t app . | | Inspect layers | docker history myimage | | Check disk | docker system df | | Clean all | docker system prune -a --volumes |

Docker Pipeline Optimization?

Efficient Docker builds are crucial for CI/CD performance. Our team offers:

  • Build time optimization (10x faster builds)
  • Image size reduction strategies
  • Multi-architecture build pipelines
  • Registry security hardening

Get containerization help

Weekly AI Security & Automation Digest

Get the latest on AI Security, workflow automation, secure integrations, and custom platform development delivered weekly.

No spam. Unsubscribe anytime.

Related Articles

DevSecOps

Kubernetes CrashLoopBackOff: Complete Troubleshooting Guide

Fix Kubernetes CrashLoopBackOff errors including OOMKilled, failed health checks, missing secrets, image pull errors, and configuration issues with step-by-step solutions.

•6 min read
DevSecOps

GitHub Actions: Common CI/CD Errors and How to Fix Them

Troubleshoot GitHub Actions errors including permission denied, checkout failures, secret exposure, artifact issues, and workflow timeout fixes with practical solutions.

•6 min read
DevSecOps

Terraform State Lock Errors: How to Fix and Prevent Them

Troubleshoot Terraform state lock errors including lock acquisition failed, state file locked, DynamoDB errors, and S3 backend issues with safe unlock procedures.

•6 min read
← Back to Blog