Docker common errors and fixes with practical examples: a hands-on troubleshooting guide

Intro

Docker errors can look cryptic, but most trace back to a small set of repeatable causes. This guide maps the most common errors to root causes, gives a step-by-step diagnostic flow, and shows safe, modern fixes you can verify locally before rolling out.

Who this is for:

• Developers shipping services in containers
• DevOps engineers standardizing incident response
• Startup teams building reliable delivery pipelines

What you will get:

• A repeatable workflow for fast, low-risk diagnosis
• Practical fixes for build, run, network, volume, and registry issues
• A small local pilot to lock in improvements before scaling

Workflow Overview

Use this flow to cut through noise and reduce rework:

1. Reproduce exactly

• Capture the full command and versions:
• docker --version
• docker compose version
• docker info (redact secrets)
• docker buildx version
• docker context ls
• Re-run with full logs:
• docker build --progress=plain .
• docker run --rm -it IMAGE[:TAG] COMMAND
• docker compose up --build and docker compose logs -f

1. Read the whole error

• Many Docker errors show a short summary and the real cause a few lines above. Scroll and capture the first failing line.

1. Minimize the scenario

• Create a tiny repro Dockerfile and isolate the failing step with a single COPY or RUN.
• Replace your app with a known-good base (e.g., alpine, nginx:alpine) to confirm infra vs app problems.

1. Diff configuration

• Compare working vs failing tags, platforms, and mounts.
• Inspect Dockerfile stage by stage; check docker compose config outputs.
• Confirm the build context and any overrides.

1. Apply the smallest safe fix

• Prefer config changes (paths, permissions, platform) before code edits.

1. Verify locally on a clean slate

• Optionally clean unused data: docker system df then docker system prune -f (caution: removes unused resources)
• Rebuild: docker build --no-cache .
• Run: docker run --rm IMAGE[:TAG]

Common Build Errors

1) COPY failed: file not found in build context

Symptoms:

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

Why it happens:

• The file is outside the build context (the path you pass to docker build).
• .dockerignore excludes the file or its parent directory.

How to diagnose:

• Confirm context: docker build -f app/Dockerfile ./app vs docker build -f app/Dockerfile .
• List files Docker sees: tar -cz . | tar -tz | head (run in the intended context directory)
• Inspect .dockerignore patterns that might exclude needed files.

Fix:

• Build from the correct directory and adjust paths.
• Update .dockerignore to keep required files.

Example:

# Wrong: building from repo root while Dockerfile assumes ./app context
docker build -t myapp -f app/Dockerfile .

# Right: pass ./app as the build context
docker build -t myapp -f app/Dockerfile ./app

2) exec format error (architecture mismatch)

Symptoms:

• standard_init_linux.go:... exec format error
• Image runs on one machine but not on another (e.g., ARM laptop vs AMD64 server).

Why it happens:

• The image platform does not match the host or target node.

How to diagnose:

• Check host arch: uname -m
• Check image platforms: docker buildx imagetools inspect IMAGE:TAG

Fix:

• Build or pull for the right platform using BuildKit/Buildx.

Examples:

# Force platform at build or run time
docker buildx build --platform linux/amd64 -t myapp:amd64 .
docker run --rm --platform linux/amd64 myapp:amd64

# Build a multi-arch image and push a manifest list
docker buildx create --use --name multi
docker buildx build --platform linux/amd64,linux/arm64 -t registry.example.com/myorg/myapp:1.0 --push .

3) no space left on device

Symptoms:

• Builds fail writing layers or during package installs.

Why it happens:

• Docker images, layers, and build cache filled the disk.

How to diagnose:

• docker system df
• On Linux: df -h and du -sh /var/lib/docker/* (path may vary)

Fix:

# Free space (use with care)
docker system prune -f
docker image prune -a -f
docker volume prune -f
# For build cache specifically
docker builder prune -f

Practical tips:

• Use multi-stage builds to avoid carrying build tools into final images.
• Clean package caches in the same RUN layer (e.g., apt-get clean && rm -rf /var/lib/apt/lists/*).
• Use BuildKit cache mounts to speed installs without bloating layers:

# Example for pip
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install --no-cache-dir -r requirements.txt

4) RUN fails due to shell or line endings

Symptoms:

• /bin/sh: 1: script.sh: not found
• exec user process caused: no such file or directory

Why it happens:

• Windows CRLF line endings, missing executable bit, wrong shebang, or using bash when image only has sh.

Fix:

# Normalize line endings on commit
git config core.autocrlf input

# Convert files if needed
dos2unix script.sh

# Ensure permissions and a valid shebang
chmod +x script.sh
sed -n '1p' script.sh  # should start with #!/bin/sh or #!/usr/bin/env bash

If you need Bash features, explicitly set the shell in the Dockerfile:

SHELL ["/bin/bash", "-o", "pipefail", "-c"]

5) Build cache confusion

Symptoms:

• Old dependencies persist; changes do not apply as expected.

Fix and verification:

# Show full step output for cache decisions
docker build --progress=plain .

# Force fresh layers when needed
docker build --no-cache --pull .

Best practice: place the most stable steps (system deps) before copying app code to maximize cache reuse.

Run and Compose Errors

1) Port is already allocated

Symptoms:

• Error starting userland proxy: listen tcp 0.0.0.0:80: bind: address already in use

How to diagnose:

• docker ps --format 'table {{.ID}}\t{{.Image}}\t{{.Ports}}'
• lsof -i :80 (Linux/macOS) or Get-NetTCPConnection -LocalPort 80 (PowerShell)

Fix:

# Remap the host port
docker run -p 8080:80 nginx:alpine

Compose example:

services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"

2) exec user process caused: no such file or directory

Symptoms:

• Container exits immediately on start.

Why it happens:

• Entrypoint/CMD points to a missing file or has CRLF line endings.

How to diagnose and fix:

# Inspect files inside the image
docker run --rm -it --entrypoint sh myapp:tag -c 'ls -l /app && file /app/entrypoint.sh && cat -A /app/entrypoint.sh | head'
# Then normalize line endings and permissions as in build fixes

Ensure ENTRYPOINT/CMD paths are absolute and files exist in the final stage of multi-stage builds.

3) OCI runtime create failed: permission denied

Why it happens:

• Bind mount permissions, rootless Docker limits, or SELinux labels on Linux.

Fixes:

# Align container user with host files
docker run -u $(id -u):$(id -g) -v "$PWD/data":/data myapp:tag

# On SELinux hosts, label bind mounts (:z shared, :Z private)
docker run -v "$PWD/data":/data:Z myapp:tag

If you require root inside the container under rootless Docker, reconsider the need or switch to a privileged environment only where justified.

4) Network not found in Compose

Symptoms:

• network mynet declared as external, but could not be found

Fix:

# Create the network explicitly
docker network create mynet
# Or let Compose manage it by removing external: true

Verify with docker network ls and docker compose config.

5) Container cannot reach host service via localhost

Symptoms:

• App inside container cannot reach a host service on localhost.

Fix:

• Use host.docker.internal (macOS/Windows, and recent Linux Desktop) or the Docker bridge IP (often 172.17.0.1 on Linux).

curl http://host.docker.internal:3000

Networking and DNS Errors

1) Temporary failure in name resolution

Symptoms:

• DNS lookups fail inside the container.

Why it happens:

• Host DNS/unusual resolver, corporate proxy, or blocked egress.

How to diagnose and fix:

# Test DNS inside a throwaway container
docker run --rm busybox nslookup google.com || true

# Override DNS per-container (quick test)
docker run --rm --dns 8.8.8.8 busybox nslookup google.com

Daemon-wide DNS (then restart Docker):

{
  "dns": ["8.8.8.8", "1.1.1.1"]
}

Behind a proxy: set HTTP_PROXY, HTTPS_PROXY, and NO_PROXY for both build and run. For builds:

docker build --build-arg HTTP_PROXY=http://proxy:3128 --build-arg HTTPS_PROXY=http://proxy:3128 .

2) Cannot pull: lookup registry-1.docker.io: no such host

Fix:

• Apply the same DNS steps above.
• Verify host connectivity: curl -I https://registry-1.docker.io.
• Consider a registry mirror via "registry-mirrors" in daemon.json if your network is restrictive.

3) certificate signed by unknown authority (corporate CA)

Symptoms:

• Pulls/builds to internal registries fail TLS verification.

Fix inside the image (runtime trust):

COPY corp-ca.crt /usr/local/share/ca-certificates/
RUN update-ca-certificates

For the Docker daemon trust store, install your CA per OS guidance and restart Docker.

Volumes and Permissions Errors

1) Permission denied on bind mounts

Symptoms:

• Application cannot read/write mounted files.

Why it happens:

• Host UID/GID mismatch with the container user; SELinux labels on Linux.

How to diagnose:

• On host: stat -c "%u:%g" data/
• In container: id, ls -l /data

Fixes:

# Run as matching UID/GID
docker run -u $(id -u):$(id -g) -v "$PWD/data":/data myapp:tag

# Prefer named volumes for portable writes when possible
docker volume create appdata
docker run -v appdata:/data myapp:tag

Compose example (with SELinux):

volumes:
  data: {}
services:
  app:
    image: myapp:tag
    user: "${UID:-1000}:${GID:-1000}"
    volumes:
      - data:/data
      - "${PWD}/data:/data-host:Z"

2) File sharing not enabled (macOS/Windows)

Symptoms:

• Bind mount appears empty or fails.

Fix:

• Enable file sharing for the drive/folder in Docker Desktop settings. On Windows with WSL 2, prefer mounting from the Linux filesystem (e.g., under ~/project) for better performance.

Images and Registry Errors

1) pull access denied, repository does not exist or may require authorization

Fix:

# Verify image name and tag
docker pull registry.example.com/team/app:1.2.3

# Authenticate to the registry
docker login registry.example.com

2) manifest unknown or not found

Why it happens:

• Tag does not exist or the manifest for your platform is missing.

Fix:

# Inspect available platforms
docker buildx imagetools inspect IMAGE:TAG

# Pull for a specific platform if available
docker pull --platform linux/amd64 IMAGE:TAG

3) Rate limit exceeded (public registries)

Fix:

• Authenticate to increase limits.
• Use a private mirror or registry cache.
• Consolidate and pin base images to reduce churn.

Performance and Resource Errors

1) OOMKilled or memory pressure

Symptoms:

• Container exits; docker inspect shows "OOMKilled": true.

How to diagnose:

• docker stats to watch memory usage in real time.
• Check app logs for memory spikes.

Fix:

# Set limits at run time
docker run --memory=512m --memory-swap=512m myapp:tag

Compose (applies in non-Swarm Compose implementations):

services:
  app:
    image: myapp:tag
    mem_limit: 512m
    cpus: 1.0

Tune application memory usage and raise limits only as needed.

2) Slow builds due to cache misses

Fix:

• Reorder Dockerfile: install OS deps before copying frequently changing app code.
• Use multi-stage builds to keep final images small.
• Use BuildKit cache mounts for language/package caches (pip, npm, go, cargo).
• Pin dependency versions to make cache hits predictable.

Example (Python):

FROM python:3.12-slim AS base
WORKDIR /app
COPY requirements.txt .
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "app.py"]

Local Pilot Plan

Goal

• Prove common errors are caught and fixed quickly on a single service.

Scope

• One Dockerfile (e.g., minimal Nginx or Python service).
• One compose.yaml exposing an HTTP port and a writable data directory.

Steps

1. Create a tiny service

FROM nginx:alpine
COPY ./public /usr/share/nginx/html

1. Add common failure checks

• Remove a file from public and see COPY fail; fix by adjusting context and .dockerignore.
• Introduce CRLF in a shell script; fix with LF and chmod +x.
• Force a platform mismatch; run with --platform to verify behavior.
• Bind mount a data dir; test permissions using matching UIDs and :Z on SELinux.

1. Instrument quick diagnostics (optional Makefile)

run:
	docker compose up --build
shell:
	docker run --rm -it --entrypoint sh myapp:dev
clean:
	docker system prune -f

1. Document exact fixes

• Keep a short troubleshooting.md with error text, cause, and the command used to fix it.

1. Extend gradually

• Add a second service (e.g., API) and a user-defined network.
• Add image pulls from a private registry to validate auth and tag handling.

Conclusion

Most Docker problems repeat across projects: path and context mistakes, platform mismatches, DNS/proxy quirks, and permissions on mounts. With a simple workflow, modern BuildKit/Buildx practices, and the fixes above, you can diagnose and resolve issues quickly and safely. Start with the local pilot, capture what works, and apply the same patterns to Docker Compose, Kubernetes, and CI pipelines.