How to Debug Docker Containers: A Practical Guide

When Containers Misbehave

Even the best-configured containers sometimes fail. Maybe a service won't start, a container keeps restarting, or something just isn't working as expected. Debugging Docker containers is a skill every homelab owner needs to master.

This guide will walk you through systematic debugging techniques that will help you solve most container issues quickly.

Step 1: Check Container Status

Start by understanding what state your container is in:

# List all containers (including stopped ones)
docker ps -a

# Get detailed container information
docker inspect <container_name>

# Check container health status
docker inspect --format='{{.State.Health.Status}}' <container_name>

Look for the STATUS column. Common states include:

• Up: Container is running
• Exited (0): Container stopped normally
• Exited (1): Container crashed with an error
• Restarting: Container is in a restart loop

Step 2: Read the Logs

Container logs are your best friend when debugging. Most issues can be diagnosed by reading what the application is telling you:

# View all logs
docker logs <container_name>

# Follow logs in real-time
docker logs -f <container_name>

# Show last 100 lines
docker logs --tail 100 <container_name>

# Show logs with timestamps
docker logs -t <container_name>

# For docker-compose
docker compose logs -f <service_name>

Look for error messages, stack traces, or configuration warnings. Most applications clearly state what went wrong.

Step 3: Get Inside the Container

Sometimes you need to explore what's happening inside a running container:

# Open a shell in a running container
docker exec -it <container_name> /bin/bash

# If bash isn't available, try sh
docker exec -it <container_name> /bin/sh

# Run a specific command
docker exec <container_name> ls -la /app

# Check environment variables
docker exec <container_name> env

Once inside, you can check file permissions, verify configurations, test network connectivity, and more.

Step 4: Debug a Crashed Container

If a container exits immediately, you can't exec into it. Use these techniques instead:

# Check logs from the crashed container
docker logs <container_name>

# Run the image with an interactive shell
docker run -it --entrypoint /bin/sh <image_name>

# Override the command to keep container alive
docker run -it <image_name> sleep infinity

This allows you to explore the container environment and manually run the startup commands to see what fails.

Step 5: Network Debugging

Network issues are common in containerized environments. Here's how to debug them:

# List Docker networks
docker network ls

# Inspect a network
docker network inspect <network_name>

# Check which networks a container is connected to
docker inspect <container_name> | grep -A 20 "Networks"

# Test connectivity from inside a container
docker exec <container_name> ping <hostname>
docker exec <container_name> curl -v http://other-service:8080

Remember that containers in the same Docker Compose file automatically share a network and can reach each other by service name.

Common Issues and Solutions

Port Already in Use

# Find what's using the port
sudo lsof -i :8080
# or
sudo netstat -tulpn | grep 8080

Permission Denied

# Check file ownership
docker exec <container_name> ls -la /path/to/files

# Fix permissions (example for user 1000)
sudo chown -R 1000:1000 ./data

Container Keeps Restarting

# Check restart count and reason
docker inspect <container_name> | grep -A 5 "RestartCount"

# Temporarily disable restart policy
docker update --restart=no <container_name>

Resource Issues

Sometimes containers fail due to resource constraints:

# Check container resource usage
docker stats <container_name>

# Check if container was killed due to OOM
docker inspect <container_name> | grep OOMKilled

# View system-wide Docker resource usage
docker system df

If a container is getting OOM killed, increase the memory limit in your docker-compose.yml or reduce the application's memory usage.

Pro Debugging Tips

• Always check logs first - they usually tell you exactly what's wrong
• Compare your config with the official image documentation
• Search the image's GitHub issues for similar problems
• Use docker events to watch real-time container events
• When in doubt, rebuild: docker compose down && docker compose up -d --force-recreate