How to Troubleshoot and Debug Docker Containers Like a Pro

Stop guessing why your container is crashing and start treating your Docker environment like a transparent system.

When a container fails, the instinctive reaction is often to restart it and hope for the best. But "rebooting" rarely fixes the underlying configuration drift or memory leak. To troubleshoot Docker like a pro, you need a systematic approach to isolate whether the problem lies in the application code, the Dockerfile, the network, or the host resources.

Here is the professional playbook for diagnosing and fixing Docker container issues.

1. The First Line of Defense: Logs

Before you dive into the container, look at what it’s trying to tell you. Most applications are configured to send logs to stdout and stderr, which Docker captures.

The Basic Check: docker logs <container_id>

The Pro Move: If the container is crashing in a loop, use the --tail and -f (follow) flags to see the final moments of the process in real-time: docker logs -f --tail 100 <container_id>

If your logs are empty, check if your application is writing to a file inside the container instead of the standard output. If it is, you'll need to move to the next step.

2. Getting Under the Hood: docker exec

If the container is running but behaving strangely, you need to get inside. The exec command allows you to run a new process (usually a shell) inside the existing container.

docker exec -it <container_id> /bin/sh (or /bin/bash)

Once inside, check these three things: * Environment Variables: Run env to ensure your secrets and config keys are actually present. * File Permissions: Ensure the user running the app has rights to the /app or /data directories. * Config Files: Use cat to verify that your .conf or .yaml files were copied correctly during the build.

3. Debugging "Dead" Containers

What happens when a container crashes immediately upon startup? You can't exec into a stopped container.

The Workaround: Override the entrypoint to force the container to stay alive. By changing the command to a shell, you can start the container and then poke around to see why the original app failed.

docker run -it --entrypoint /bin/sh <image_name>

This allows you to manually run the startup script or command and watch it fail in a live shell.

4. Inspecting the Blueprint

Sometimes the issue isn't the code, but the "envelope" the code lives in. docker inspect provides a massive JSON output of every configuration detail assigned to the container.

What to look for in the Inspect output: * Network Settings: Is it attached to the correct bridge network? * Mounts: Are your volumes mapped to the correct paths on the host? * Healthchecks: Is Docker killing the container because a health check is failing?

5. Networking and Connectivity Issues

"I can't connect to my database" is the most common Docker complaint.

The Troubleshooting Flow: 1. Ping the Service: Use docker exec to get into the app container and try to ping the DB container by its service name. 2. Check Ports: Run docker ps to ensure your port mapping is correct (e.g., 8080:80). Remember: the first port is the host, the second is the container. 3. Curl the Endpoint: If you have curl installed in the container, try curl -v localhost:<port> to see if the service is listening internally.

6. Resource Exhaustion and "OOMKilled"

If your container disappears without a trace in the logs, it might have been killed by the Linux kernel for using too much memory (Out Of Memory).

Run docker inspect <container_id> and look for the State section. If you see "OOMKilled": true, your container hit its memory limit.

The Fix: * Increase the memory limit in your docker-compose.yml. * Profile your application for memory leaks. * Check if the host machine itself is out of RAM.

7. Using docker stats for Real-time Health

For performance-related bugs (CPU spikes or memory creep), don't guess—measure.

docker stats

This provides a live stream of CPU usage, memory consumption, and network I/O for all running containers. If you see CPU usage pinned at 100%, you likely have an infinite loop or a resource-heavy process that needs optimization.

Summary Checklist

When a container fails, follow this sequence: 1. docker logs $\rightarrow$ Is there an error message? 2. docker ps -a $\rightarrow$ Did it exit with a specific code (e.g., 137 for OOM)? 3. docker exec $\rightarrow$ Are the files and environment variables correct? 4. docker inspect $\rightarrow$ Are the ports and volumes mapped correctly? 5. docker stats $\rightarrow$ Is it choking on resources?