docker-troubleshoot

name	docker-troubleshoot
description	Debug Docker container issues including crashes, OOM kills, daemon failures, and build errors. Use when containers won't start, keep restarting, or Docker daemon is unresponsive.

Docker Troubleshooting

Quick Diagnosis

Step 1: Check container status

docker ps -a --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

Look for containers in Exited, Restarting, or Dead state.

Step 2: Check container logs

docker logs <container_name> --tail 100
docker logs <container_name> --tail 100 --timestamps

Step 3: Check system resources

# Memory
free -m
# Disk
df -h
# Docker disk usage
docker system df

Common Issues

Container keeps restarting

# Check exit code
docker inspect <container> --format='{{.State.ExitCode}}'
# Exit code 137 = OOM killed
# Exit code 1 = Application error
# Exit code 0 = Normal exit

# Check OOM kills
dmesg | grep -i "oom\|killed"

Out of memory (OOM)

# Add memory limits to container
docker run -d --memory=2g --memory-swap=4g ...


docker system prune -f
docker builder prune -f
docker image prune -a -f