Docker
Troubleshooting

A systematic approach prevents random guessing and saves hours of debugging time.

# Check exit code of a stopped container
docker inspect --format='{{.State.ExitCode}}' my-container

# See full state including OOMKilled flag
docker inspect --format='{{json .State}}' my-container | jq .

Container logs capture everything written to stdout and stderr by the main process (PID 1).

# Basic log viewing
docker logs my-container                  # all logs
docker logs --tail 100 my-container       # last 100 lines
docker logs --since 5m my-container       # last 5 minutes
docker logs -f my-container               # follow (live tail)
docker logs --timestamps my-container     # show timestamps

# Combine flags for precision
docker logs --since 2024-01-01T10:00:00 --until 2024-01-01T11:00:00 my-app

# Check which log driver a container uses
docker inspect --format='{{.HostConfig.LogConfig.Type}}' my-container

# Limit log file size in daemon.json or per-container
docker run --log-opt max-size=10m --log-opt max-file=3 my-image

Shell into a running container to inspect state, test connectivity, and debug in real time.

# Interactive shell
docker exec -it my-container /bin/bash
docker exec -it my-container /bin/sh         # alpine / minimal images

# Run a single command
docker exec my-container cat /etc/hosts
docker exec my-container env                 # check environment variables
docker exec my-container ps aux              # see running processes

# As a specific user
docker exec -u root my-container apt-get update

# Set environment variables for the exec session
docker exec -e DEBUG=true my-container ./run-diagnostics.sh

docker inspect returns the complete JSON configuration of any Docker object — the single most powerful diagnostic command.

# Full JSON output (pipe to jq for readability)
docker inspect my-container | jq .

# Targeted queries with Go templates
docker inspect -f '{{.State.Status}}' my-container
docker inspect -f '{{.NetworkSettings.IPAddress}}' my-container
docker inspect -f '{{range .Mounts}}{{.Source}} -> {{.Destination}}{{"\n"}}{{end}}' my-container
docker inspect -f '{{json .Config.Env}}' my-container | jq .

# Inspect images and networks too
docker image inspect nginx:latest -f '{{.Config.ExposedPorts}}'
docker network inspect bridge | jq '.[0].Containers'

Real-time resource usage for all running containers — your first stop for performance issues.

# Live dashboard (updates every second)
docker stats

# One-shot snapshot (good for scripts)
docker stats --no-stream

# Specific containers with custom format
docker stats --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.NetIO}}" web api db

# Check memory limits vs actual usage
docker inspect -f '{{.HostConfig.Memory}}' my-container   # 0 = unlimited

Build failures happen at image creation time. The key is identifying which layer failed and why.

# Verbose build output
docker build --progress=plain --no-cache -t myapp .

# Debug a failed multi-stage build at a specific stage
docker build --target=builder -t myapp-debug .
docker run -it myapp-debug /bin/sh

# With BuildKit, use inline cache for CI
docker build --build-arg BUILDKIT_INLINE_CACHE=1 -t myapp .

Docker caches each layer. When the cache breaks unexpectedly — or does not break when it should — you get confusing behaviour.

# BAD: cache busts on any source change
COPY . /app
RUN npm install

# GOOD: install deps first, then copy source
COPY package.json package-lock.json /app/
RUN npm install
COPY . /app

# Bust cache from a specific point using build arg
ARG CACHE_BUST=1
RUN git clone https://github.com/org/repo.git

Networking is the most common source of "works locally, fails in Docker" issues.

# Debug networking step by step
docker network ls                                        # list networks
docker network inspect my-network                        # show connected containers
docker exec my-container cat /etc/resolv.conf            # check DNS config
docker exec my-container ping other-container             # test connectivity
docker exec my-container curl -v http://api:3000/health  # test service discovery

# Create a user-defined network for DNS resolution
docker network create my-app-net
docker run --network my-app-net --name api my-api-image
docker run --network my-app-net --name web my-web-image  # can reach "api" by name

Bind mounts and volumes cause some of the most frustrating debugging sessions, especially around file permissions.

# Debug volume/permission issues
docker exec my-container ls -la /app          # check ownership
docker exec my-container id                    # who am I in the container?
docker inspect -f '{{json .Mounts}}' my-container | jq .  # list mounts

# Fix ownership at runtime
docker exec -u root my-container chown -R 1000:1000 /data

# SELinux context (Fedora/RHEL)
docker run -v /host/data:/data:z my-image     # shared label
docker run -v /host/data:/data:Z my-image     # private label

A container in a restart loop is one of the most common and frustrating patterns. The key is breaking the cycle to inspect state.

# Full restart debugging workflow
docker ps -a | grep my-app                           # see status & restart count
docker logs --tail 50 my-app                         # read the crash output
docker inspect -f '{{.State.ExitCode}}' my-app       # what exit code?
docker inspect -f '{{.State.OOMKilled}}' my-app      # was it OOM?
docker update --restart=no my-app                    # stop the loop
docker run -it --entrypoint /bin/sh my-image         # debug interactively

# Debug pull issues
docker pull --platform linux/amd64 nginx:latest      # force platform
docker manifest inspect nginx:latest                  # check available architectures
docker login ghcr.io                                  # authenticate to GitHub registry

# Check rate limit status (Docker Hub)
curl -s "https://auth.docker.io/token?service=registry.docker.io&scope=repository:library/nginx:pull" \
  | jq -r .token | xargs -I {} curl -sI -H "Authorization: Bearer {}" \
  https://registry-1.docker.io/v2/library/nginx/manifests/latest 2>&1 | grep ratelimit

Docker can silently consume tens of gigabytes with old images, stopped containers, and unused volumes.

# See what Docker is using
docker system df                     # summary: images, containers, volumes, build cache
docker system df -v                  # detailed breakdown per object

# The nuclear option: remove everything unused
docker system prune -a --volumes     # WARNING: removes all stopped containers,
                                     # unused images, unused networks, and volumes

# Find the biggest images
docker images --format "{{.Size}}\t{{.Repository}}:{{.Tag}}" | sort -hr | head -10

# Find containers writing lots of data to their writable layer
docker ps -s --format "table {{.Names}}\t{{.Size}}"

When containers are slow, systematically check CPU, memory, I/O, and networking.

# Host-level process inspection
docker inspect -f '{{.State.Pid}}' my-container     # get PID on host
sudo strace -p <PID> -c                             # syscall profiling
sudo nsenter -t <PID> -n ss -tlnp                   # network sockets from container namespace

When the problem is not the container but Docker itself — daemon logs reveal engine-level errors.

# Check daemon status
sudo systemctl status docker
sudo journalctl -u docker.service --since "1 hour ago"

# Enable debug logging
sudo tee /etc/docker/daemon.json <<'EOF'
{
  "debug": true,
  "log-level": "debug"
}
EOF
sudo systemctl reload docker

Third-party tools that make Docker troubleshooting significantly easier.

# Install and run common tools
brew install dive lazydocker ctop       # macOS
apt install -y strace ltrace tcpdump    # Linux debugging essentials

# Use docker debug (Docker Desktop 4.27+)
docker debug my-container               # drops into a shell with tools pre-installed