Kenhuang Academy
  • English

      • 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 CodeMeaningSolution
      0Normal exitEnsure CMD/ENTRYPOINT runs a foreground process
      1Application errorCheck logs for app errors
      137OOM KilledIncrease memory limit -m
      139SegfaultCheck application code
      143SIGTERMNormal 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