Docker Troubleshooting - Docker

Every Docker user eventually runs into issues. Here is the standard workflow for debugging them.

1. Container Won't Start (Exits Immediately)

If your container starts but stops immediately, it's usually because the main process failed.

Check Logs

Action:

docker logs my-failed-container

Result:

Traceback (most recent call last):
  File "app.py", line 5, in <module>
    import database_driver
ModuleNotFoundError: No module named 'database_driver'

(The logs tell you exactly what went wrong in your application code)

2. Debugging Inside a Running Container

Sometimes you need to see what's happening inside.

Interactive Shell

Action:

docker exec -it my-running-app /bin/sh

Result:

/app # ls -la
/app # curl localhost:8080

(You can now manually test connectivity and check files)

3. Network Issues (No Connectivity)

If your container can't talk to a database or the internet.

Check Network Inspection

Action:

docker network inspect app-net

Result:

"Containers": {
    "a1b2c3d4e5f6": {
        "Name": "web",
        "IPv4Address": "172.18.0.2/16"
    }
}

(Verify if the containers are on the same network)

4. Disk Space Full

If you get errors like no space left on device.

Quick Cleanup

Action:

# Remove ALL unused containers, networks, images, and build cache
docker system prune -a --volumes

Result:

Total reclaimed space: 14.23GB

Summary: Debugging Workflow

docker ps -a: Check the exit code.
docker logs: Read the application errors.
docker inspect: Check IP addresses and volume mounts.
docker exec: Test manually from inside the container.
docker stats: Check if it's hitting a memory/CPU limit.