Docker Logs, Debugging and Troubleshooting Guide

Docker Logs, Debugging and Troubleshooting Guide#

Docker troubleshooting becomes easier when you follow a clear flow: check container status, read logs, inspect configuration, verify ports, test networks, and review volumes.

Quick troubleshooting flow#

1. Check if the container is running.
2. Read logs.
3. Check exit code.
4. Inspect ports, mounts, and environment variables.
5. Exec into the container if it is running.
6. Test network connectivity.
7. Rebuild image if needed.

Check container status#

docker ps docker ps -a

Read logs#

docker logs CONTAINER_NAME docker logs -f CONTAINER_NAME docker logs --tail 100 CONTAINER_NAME

Inspect container details#

docker inspect CONTAINER_NAME

Inspect output can show environment variables, mounts, ports, network settings, image ID, restart policy, and exit code.

Exec inside a running container#

docker exec -it CONTAINER_NAME sh docker exec -it CONTAINER_NAME bash

Common issue: container exits immediately#

Usually the main process finished or failed. Check logs and exit code.

docker ps -a docker logs CONTAINER_NAME

Common issue: port not working#

docker run -d -p 8080:80 nginx docker port CONTAINER_NAME

Check whether the app listens on the correct container port and whether the host port is already used.

Common issue: container cannot reach database#

• Check if both containers are on the same network.
• Use service/container name instead of localhost.
• Check database startup readiness.
• Check credentials and environment variables.

Network debug commands#

docker network ls docker network inspect NETWORK_NAME docker exec -it app sh ping db nslookup db

Volume debug commands#

docker volume ls docker volume inspect VOLUME_NAME docker inspect CONTAINER_NAME | grep Mounts -A 20

Common mistakes#

• Debugging randomly without reading logs.
• Using localhost inside one container to reach another container.
• Forgetting port publishing.
• Deleting containers before checking logs.
• Removing volumes during cleanup and losing data.

Best practices#

• Always start with docker ps -a and logs.
• Name containers and services clearly.
• Use health checks for important apps.
• Keep Dockerfiles simple and reproducible.
• Document common fixes for your team.

Related Melochip guides#

• Docker Learning Path
• Docker Commands Explained
• GitLab CI/CD Troubleshooting Guide

Official references#

• docker logs reference
• docker inspect reference