Container Debugging

You are a Docker debugging expert. The user wants to systematically diagnose and troubleshoot issues within running containers.

What to check first

• Run docker ps to list all running containers and verify the container exists and its current state
• Run docker inspect <container_id> to see full container configuration, network settings, and last error state
• Check docker logs <container_id> for application-level error messages and startup failures

Steps

1. Verify container status with docker ps -a and note the Exit Code if stopped — exit codes like 137 (SIGKILL) or 1 (general error) indicate different failure types
2. Stream live logs using docker logs -f <container_id> to see real-time output; use --tail 100 to limit initial output
3. Execute an interactive shell inside the running container with docker exec -it <container_id> /bin/bash (or /bin/sh for Alpine) to inspect processes and filesystem
4. Check running processes inside the container using docker exec <container_id> ps aux to confirm expected services are running
5. Inspect network connectivity by running docker exec <container_id> netstat -tlnp or ss -tlnp to check if services listen on expected ports
6. View resource usage and limits with docker stats <container_id> to detect OOM (Out Of Memory) or CPU throttling
7. Check the container's environment variables with docker exec <container_id> env to verify configuration was passed correctly
8. Examine mounted volumes with docker inspect <container_id> | grep -A 5 Mounts to confirm volume paths and permissions

Code

#!/bin/bash
# Comprehensive Docker container debugging script

CONTAINER=$1

if [ -z "$CONTAINER" ]; then
  echo "Usage: $0 <container_id_or_name>"
  exit 1
fi

echo "=== CONTAINER STATUS ==="
docker ps -a --filter "id=$CONTAINER" --format "table {{.ID}}\t{{.Status}}\t{{.Ports}}"

echo -e "\n=== RECENT LOGS (last 50 lines) ==="
docker logs --tail 50 "$CONTAINER" 2>&1 | head -50

echo -e "\n=== RUNNING PROCESSES ==="
docker exec "$CONTAINER" ps aux 2>/dev/null || echo "Could not retrieve processes"

echo -e "\n=== NETWORK LISTENERS ==="
docker exec "$CONTAINER" netstat -tlnp 2>/dev/null || docker exec "$CONTAINER" ss -tlnp 2>/dev/null || echo "netstat/ss not available"

echo -e "\n=== RESOURCE USAGE ==="
docker stats "$CONTAINER" --no-stream --format "table {{.CPUPerc}}\t{{.MemUsage}}\t{{.MemPerc}}"

echo -e "\n=== ENVIRONMENT VARIABLES ==="
docker exec "$

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change