Docker Troubleshooting

This chapter covers common Docker problem diagnosis methods and solutions.

Diagnostic Tools

Container Status

docker ps -a                    # All containers
docker inspect <container>      # Detailed info
docker logs <container>         # Logs
docker logs --tail 100 -f <container>  # Follow last 100 lines
docker top <container>          # Processes
docker stats <container>        # Resource usage
docker diff <container>         # Filesystem changes

System Information

docker info                     # System info
docker version                  # Version
docker system df                # Disk usage
docker events                   # Events

Container Startup Issues

Container Exits Immediately

docker ps -a --filter "name=myapp"   # Check exit code
docker logs myapp                     # Check logs

Exit Code	Meaning	Solution
0	Normal exit	Ensure CMD/ENTRYPOINT runs a foreground process
1	Application error	Check logs for app errors
137	OOM Killed	Increase memory limit -m
139	Segfault	Check application code
143	SIGTERM	Normal stop signal

docker run -d nginx                    # ✅ nginx runs in foreground
docker run -d ubuntu sleep infinity    # ✅ Keeps container running
docker run -d ubuntu                   # ❌ No foreground process, exits immediately

Network Issues

Container Can't Access Internet

docker exec myapp ping 8.8.8.8
docker exec myapp nslookup google.com

Solution:

docker run --dns 8.8.8.8 myapp
# Or configure in daemon.json
{ "dns": ["8.8.8.8", "8.8.4.4"] }

Containers Can't Communicate

# Use custom network
docker network create mynet
docker run -d --name app1 --network mynet nginx
docker run -d --name app2 --network mynet nginx
docker exec app1 ping app2

Port Conflicts

docker ps --format "table {{.Names}}\t{{.Ports}}"
ss -tlnp | grep :80        # Linux
netstat -ano | findstr :80  # Windows

Storage Issues

Disk Space Full

docker system df
docker system prune -a
docker image prune
docker volume prune
docker container prune
docker builder prune

Image Issues

Pull Failures

# Configure registry mirrors in /etc/docker/daemon.json
{ "registry-mirrors": ["https://mirror.gcr.io"] }
sudo systemctl restart docker

Build Failures

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

Docker Daemon Issues

Service Won't Start

sudo systemctl status docker
sudo journalctl -xu docker.service
cat /etc/docker/daemon.json | python3 -m json.tool   # Validate config
sudo systemctl restart docker

Performance Issues

High CPU Usage

docker stats
docker exec -it myapp top
docker update --cpus 1 myapp

Memory Leaks

docker stats --format "table {{.Name}}\t{{.MemUsage}}\t{{.MemPerc}}"
docker update -m 512m myapp
docker inspect myapp | grep -i oom

Troubleshooting Workflow

1. docker ps -a          → Check container status
2. docker logs <id>      → Check logs
3. docker inspect <id>   → Check configuration
4. docker exec -it <id> sh → Enter container to debug
5. docker stats          → Check resource usage
6. docker system df      → Check disk usage
7. docker events         → Check system events

Chapter Summary

Docker troubleshooting centers on using docker logs, docker inspect, and docker stats. Most issues fall into startup, networking, storage, or performance categories.

Further Reading

• Docker Troubleshooting Documentation
• Docker Logging