🔧 Docker Troubleshooting

Find your exact problem and fix it — each section follows Problem → Symptoms → Diagnose → Fix.

🩺 Run These First — Every Time

These 5 commands give you the full picture within 60 seconds and resolve most issues without deeper investigation.

What state is the container in?

docker ps -a

Check STATUS — Exited (1) = crash · Exited (0) = ran and finished · Restarting = crash-loop.

What did it say before dying?

docker logs <container> --tail 100

The error is almost always in the last 10 lines. Pipe to grep -i error if output is large.

Was it killed by the kernel (OOM)?

docker inspect --format '{{.State.OOMKilled}}' <container>

If true → increase memory limit. OOM kills leave no app-level log.

What resources is it consuming?

docker stats --no-stream

CPU pegged at 100 % = throttled. MEM near limit = impending OOM. BLOCK I/O high = disk bottleneck.

What events happened on the host?

docker events --since 30m

Shows OOM kills, restarts, and daemon signals invisible in container logs.

📊 Exit Code — What Happened?

Exit Code	Meaning	Go To
0	Clean finish — process ran and exited normally	Container Won't Stay Up tab
1	App crash / unhandled exception	`docker logs` for stack trace
127	Binary not found in image	Build Errors tab
137	OOM kill (SIGKILL)	Crashes & OOM tab
139	Segfault (SIGSEGV)	App bug — check binary
143	Graceful shutdown (SIGTERM)	Check restart policy

🚫

Problem: Container status is `Exited (127)` — command not found

Symptoms

You see: exec: "mybin": executable file not found in $PATH or exit code 127.

Diagnose

docker logs <container> --tail 20
# Verify binary exists in image
docker run --rm --entrypoint sh myimage -c "which mybin && mybin --version"

Fix

Binary not installed

Add the package to your Dockerfile.

RUN apt-get update && apt-get install -y mypackage

Wrong CMD path

Use the absolute path or verify the binary name.

CMD ["/usr/local/bin/mybin", "--flag"]

🔑

Problem: Container exits with error — missing environment variable

Symptoms

You see: KeyError: 'DB_URL' / undefined environment variable / connection refused on startup.

Diagnose

docker inspect <container> | grep -A30 '"Env"'
docker logs <container> --tail 30

Fix

Pass the missing variable

docker run -e DB_URL=postgres://host:5432/db myimage
# or via env file
docker run --env-file .env myimage

Use a default in-app

Make the app fall back to a sane default so startup isn't fatal.

🔌

Problem: Container fails — host port already bound

Symptoms

You see: Bind for 0.0.0.0:8080 failed: port is already allocated

Diagnose

ss -tlnp | grep :8080
docker ps --filter publish=8080

Fix

Use a different host port

docker run -p 8081:8080 myimage

Stop the conflicting container

docker stop $(docker ps -q --filter publish=8080)

Kill host process owning the port

lsof -ti:8080 | xargs kill -9

📦

Problem: Container exits because image / tag doesn't exist

Symptoms

You see: Unable to find image 'myimage:tag' locally or manifest unknown

Diagnose

docker images | grep myimage
docker pull myimage:tag          # try pulling explicitly

Fix

Build the image first

docker build -t myimage:tag .

Check the correct tag

docker search myimage
docker pull myimage:latest

💀

Problem: Container exits immediately with code 0 — "it just stops"

Symptoms

Confusing behaviour: Container starts, nothing seems wrong, but it's gone after a second. Exit code 0 = clean exit. Docker containers stop when their PID 1 exits.

Diagnose

docker logs <container>           # any output at all?
docker inspect --format '{{.Config.Cmd}}' <container>

Fix

Service must run in foreground

# BAD — daemon exits after forking
CMD ["nginx"]
# GOOD — blocks the process
CMD ["nginx", "-g", "daemon off;"]

One-shot script? That's fine

If CMD runs a script that exits, the container stops. Use --restart=on-failure for retry, or run interactively for debugging.

docker run -it --entrypoint /bin/sh myimage

🔄

Problem: Container keeps restarting in a loop

Symptoms

You see: docker ps shows Restarting (1) X seconds ago. Restart count keeps climbing.

Diagnose

docker logs --tail 40 <container>
docker inspect --format '{{.RestartCount}}' <container>
docker inspect --format '{{.State.ExitCode}}' <container>

Fix

Disable restart to read logs

docker update --restart=no <container>
docker stop <container>
docker logs <container>

Limit retries in production

docker run --restart=on-failure:3 myimage
# stops retrying after 3 crashes

Run interactively to reproduce

docker run --restart=no -it myimage

💥

Problem: Container killed with exit 137 — Out of Memory

Symptoms

You see: Exit code 137. No error in app logs. Container suddenly disappears.

Diagnose

docker inspect --format '{{.State.OOMKilled}}' <container>
# → true confirms OOM

dmesg | grep -i "oom\|killed"     # host kernel log
docker stats --no-stream <container>

Fix

Increase memory limit

docker run -m 2g --memory-swap 2g myimage
# compose.yml:
mem_limit: 2g

Profile memory first

docker exec -it <container> sh -c "free -m"
docker stats <container>    # watch MEM USAGE live

Fix memory leak in app

If usage grows unbounded, the app is leaking. Profile in staging before increasing limits blindly.

🐌

Problem: Container is extremely slow / high CPU

Symptoms

You see: Requests time out. docker stats shows CPU near 100 %. App responds but sluggishly.

Diagnose

docker stats --no-stream <container>
docker exec -it <container> sh -c "top -bn1 | head -20"
docker exec -it <container> sh -c "ps aux --sort=-%cpu | head"

Fix

CPU quota too tight — increase it

docker run --cpus="2.0" myimage   # was 0.5?
docker update --cpus="2.0" <running-container>

Disk I/O bottleneck

Heavy writes to the overlay2 layer are slow. Move I/O-heavy paths to a volume.

docker run -v mydata:/app/data myimage

Clean up disk — system full causes stalls

docker system df
docker system prune -af

🌐

Problem: Container can't reach the internet

Symptoms

You see: curl: (6) Could not resolve host or connect: network is unreachable inside container.

Diagnose

docker exec -it <container> ping -c3 8.8.8.8   # IP reachable?
docker exec -it <container> nslookup google.com # DNS working?
docker exec -it <container> curl -v https://example.com

Fix

iptables MASQUERADE missing

# Missing nat rule — restart Docker to restore
sudo systemctl restart docker
# Verify rule exists
sudo iptables -t nat -L POSTROUTING -n | grep MASQUERADE

Custom DNS servers

# One-off
docker run --dns 8.8.8.8 myimage
# Permanent — /etc/docker/daemon.json
{"dns": ["8.8.8.8", "1.1.1.1"]}
sudo systemctl reload docker

Behind a corporate proxy

docker run \
  -e HTTP_PROXY=http://proxy:3128 \
  -e HTTPS_PROXY=http://proxy:3128 \
  -e NO_PROXY=localhost,127.0.0.1 \
  myimage

🔗

Problem: Container A can't connect to Container B by name

Symptoms

You see: Could not resolve host: db or connection refused when using container name as hostname.

Diagnose

docker inspect <container-a> | grep -A10 '"Networks"'
# Are both containers on the same user-defined network?
docker network ls
docker network inspect <network>   # who's attached?

Fix

Use a user-defined network (required for DNS)

docker network create mynet
docker run -d --name db --network mynet postgres:15
docker run -d --name app --network mynet myapp
# Now: app → ping db  ✓

Connect a running container

docker network connect mynet <container>

⚠️ Common mistake: Using localhost to reach another container. Each container has its own network namespace — use the container name instead.

🚪

Problem: Port is mapped but not reachable from the host

Symptoms

You see: curl localhost:8080 hangs or returns Connection refused even though the container is running.

Diagnose

docker port <container>               # what's actually mapped?
docker exec -it <container> ss -tlnp  # what is the app binding to?

Fix

App binds to 127.0.0.1 — not 0.0.0.0

Port mapping only works if the app listens on all interfaces inside the container.

# BAD in your app config:
listen("127.0.0.1", 3000)
# GOOD:
listen("0.0.0.0", 3000)

Missing -p flag — port not published

docker run -p 8080:80 myimage    # host:container
# Check mapping:
docker port <container>

🏗️

Problem: `apt-get install` fails — package not found

Symptoms

You see: E: Unable to locate package xyz during docker build.

Diagnose

docker build --progress=plain .    # show full output
docker build --no-cache .          # stale cache?

Fix

Always update before install — in the same RUN

RUN apt-get update && apt-get install -y \
    curl git vim \
  && rm -rf /var/lib/apt/lists/*

Stale layer cache — rebuild without cache

docker build --no-cache -t myimage .

📂

Problem: `COPY` fails — file not found in build context

Symptoms

You see: COPY failed: file not found in build context: "src/app.py"

Diagnose

ls -la src/app.py                   # does it exist?
cat .dockerignore                    # could it be excluded?
docker build --progress=plain . 2>&1 | head -20

Fix

Paths are relative to build context, not Dockerfile

# Run from the project root, not a subdirectory
docker build -t myimage .
# or specify context explicitly
docker build -f docker/Dockerfile -t myimage .

.dockerignore is excluding the file

Open .dockerignore and remove or narrow the pattern that's blocking the file.

🐘

Problem: Image is huge — build takes forever or push fails

Symptoms

You see: docker images shows image size > 1 GB. docker push is extremely slow.

Diagnose

docker history myimage             # which layer is bloated?
docker system df                   # overall disk usage

Fix

Switch to a slim base image

FROM python:3.11-slim    # not python:3.11
FROM node:20-alpine      # not node:20

Use multi-stage build

FROM golang:1.22 AS builder
COPY . . && RUN go build -o app

FROM scratch
COPY --from=builder /app/app /app
ENTRYPOINT ["/app"]

Clean up inside the same RUN

RUN apt-get install -y build-essential \
  && make install \
  && apt-get purge -y build-essential \
  && rm -rf /var/lib/apt/lists/*

⚡

Problem: Cache busted every build — rebuilds are slow

Symptoms

You see: Every code change triggers a full npm install / pip install even though dependencies didn't change.

Fix

❌ Anti-pattern

COPY . .           # all files first
RUN npm install    # cache busted on any code change

✅ Cache-friendly

COPY package*.json ./   # deps manifest first
RUN npm ci              # cached until deps change
COPY . .                # code copied last

💾

Problem: Data disappears when the container is removed

Symptoms

You see: Database is empty after docker rm and docker run. Files written inside the container are gone.

Diagnose

docker inspect <container> | grep -A20 '"Mounts"'
# Empty Mounts = no volume — data is in the ephemeral layer

Fix

Attach a named volume

docker run -v pg_data:/var/lib/postgresql/data postgres:15
# Data survives docker rm; lost only on docker volume rm

Use a bind mount (dev)

docker run -v /host/uploads:/app/uploads myimage
# Data lives in /host/uploads on the host

🔒

Problem: Permission denied writing to a mounted volume

Symptoms

You see: Permission denied when app tries to write to /data or any bind-mounted directory.

Diagnose

docker exec -it <container> ls -lan /data     # note UID:GID
docker inspect --format '{{.Config.User}}' <container>

Fix

Match UID on the host directory

# Container runs as UID 1000:
sudo chown -R 1000:1000 /host/data
docker run -v /host/data:/data myimage

Set ownership in Dockerfile

RUN mkdir -p /data && \
    chown -R appuser:appuser /data
USER appuser

SELinux (RHEL / Fedora) — add :z flag

docker run -v /host/data:/data:z myimage

📂

Problem: Bind mount shows an empty directory inside container

Symptoms

You see: Files exist on the host but the container sees an empty directory at the mount path.

Diagnose

docker inspect <container> | grep -A5 '"Source"'
# Verify the host path is correct and populated
ls -la /host/path

Fix

Always use absolute paths in -v

# BAD — relative path silently creates wrong dir
docker run -v data:/app/data myimage         # ← named volume, not ./data!
# GOOD
docker run -v /absolute/host/path:/app/data myimage

Host dir was auto-created empty

Docker creates the host directory if it doesn't exist — but empty. Pre-create and populate it before running.

🛑

Problem: Docker daemon fails to start — `systemctl start docker` fails

Symptoms

You see: Job for docker.service failed or all docker commands return Cannot connect to the Docker daemon.

Diagnose

sudo systemctl status docker
sudo journalctl -u docker -n 80 --no-pager   # last 80 lines of daemon log

Fix

Invalid daemon.json (most common)

python3 -m json.tool /etc/docker/daemon.json
# Fix syntax errors, then:
sudo systemctl restart docker

Stale PID / socket file

sudo rm -f /var/run/docker.pid
sudo rm -f /var/run/docker.sock
sudo systemctl start docker

Storage driver conflict

sudo journalctl -u docker | grep "storage-driver"
# daemon.json — explicitly set overlay2
{"storage-driver": "overlay2"}

🔑

Problem: `permission denied` connecting to Docker socket

Symptoms

You see: permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock

Diagnose

ls -la /var/run/docker.sock     # check ownership
id                               # are you in the docker group?
groups $USER

Fix

Add user to docker group (permanent)

sudo usermod -aG docker $USER
newgrp docker                    # apply now, without logout

Temporary — only until reboot

sudo chmod 666 /var/run/docker.sock

⚠️ Security: The docker group grants root-equivalent access. Only add trusted users in production.

📋

Problem: Container logs are missing / `docker logs` returns nothing

Symptoms

You see: docker logs <container> returns empty output even though the container is running and the app is logging.

Diagnose

docker inspect --format='{{.HostConfig.LogConfig.Type}}' <container>
# If not "json-file" → docker logs won't work

Fix

Non-default log driver active

If using journald, awslogs, etc., use the driver's native tool.

journalctl CONTAINER_NAME=<name> -n 100

App writes to file, not stdout

Docker only captures stdout/stderr. Configure your app to log to stdout, or tail the log file inside the container.

docker exec -it <container> tail -f /var/log/app.log

Log size limits — oldest lines rotated

# daemon.json — set retention
{
  "log-driver": "json-file",
  "log-opts": {"max-size": "100m", "max-file": "3"}
}

💿

Problem: `no space left on device` — Docker disk is full

Symptoms

You see: no space left on device on build, pull, or container write operations.

Diagnose

docker system df                   # breakdown by type
docker system df -v                 # per-image / per-volume detail
df -h /var/lib/docker               # host disk usage

Fix — start safe, go aggressive only if needed

BASH

docker container prune              # step 1 — stopped containers
docker image prune                  # step 2 — dangling images
docker image prune -a               # step 3 — ALL unused images
docker volume prune                 # step 4 — unused volumes
docker builder prune                # step 5 — build cache
docker system prune -af --volumes   # ☢️  nuclear — everything unused

⚠️ docker system prune -af --volumes permanently deletes all unused images and volumes. Run docker system df first to understand impact.

🩺 Run These First — Every Time

📊 Exit Code — What Happened?

Problem: Container status is Exited (127) — command not found

Binary not installed

Wrong CMD path

Problem: Container exits with error — missing environment variable

Pass the missing variable

Use a default in-app

Problem: Container fails — host port already bound

Use a different host port

Stop the conflicting container

Kill host process owning the port

Problem: Container exits because image / tag doesn't exist

Build the image first

Check the correct tag

Problem: Container exits immediately with code 0 — "it just stops"

Service must run in foreground

One-shot script? That's fine

Problem: Container keeps restarting in a loop

Disable restart to read logs

Limit retries in production

Run interactively to reproduce

Problem: Container killed with exit 137 — Out of Memory

Increase memory limit

Profile memory first

Fix memory leak in app

Problem: Container is extremely slow / high CPU

CPU quota too tight — increase it

Disk I/O bottleneck

Clean up disk — system full causes stalls

Problem: Container can't reach the internet

iptables MASQUERADE missing

Custom DNS servers

Behind a corporate proxy

Problem: Container A can't connect to Container B by name

Use a user-defined network (required for DNS)

Connect a running container

Problem: Port is mapped but not reachable from the host

App binds to 127.0.0.1 — not 0.0.0.0

Missing -p flag — port not published

Problem: apt-get install fails — package not found

Always update before install — in the same RUN

Stale layer cache — rebuild without cache

Problem: COPY fails — file not found in build context

Paths are relative to build context, not Dockerfile

.dockerignore is excluding the file

Problem: Image is huge — build takes forever or push fails

Switch to a slim base image

Use multi-stage build

Clean up inside the same RUN

Problem: Cache busted every build — rebuilds are slow

❌ Anti-pattern

✅ Cache-friendly

Problem: Data disappears when the container is removed

Attach a named volume

Use a bind mount (dev)

Problem: Permission denied writing to a mounted volume

Match UID on the host directory

Set ownership in Dockerfile

SELinux (RHEL / Fedora) — add :z flag

Problem: Bind mount shows an empty directory inside container

Always use absolute paths in -v

Host dir was auto-created empty

Problem: Docker daemon fails to start — systemctl start docker fails

Invalid daemon.json (most common)

Stale PID / socket file

Storage driver conflict

Problem: permission denied connecting to Docker socket

Add user to docker group (permanent)

Temporary — only until reboot

Problem: Container logs are missing / docker logs returns nothing

Non-default log driver active

App writes to file, not stdout

Log size limits — oldest lines rotated

Problem: no space left on device — Docker disk is full

Problem: Container status is `Exited (127)` — command not found

Problem: `apt-get install` fails — package not found

Problem: `COPY` fails — file not found in build context

Problem: Docker daemon fails to start — `systemctl start docker` fails

Problem: `permission denied` connecting to Docker socket

Problem: Container logs are missing / `docker logs` returns nothing

Problem: `no space left on device` — Docker disk is full