Troubleshooting

🔧 Docker Troubleshooting: Become the Container Detective

Imagine you’re a detective. Your containers are like little rooms in a building. Sometimes things go wrong inside those rooms—lights go out, doors get stuck, or pipes leak. Your job? Find out what’s broken and fix it!

🎯 What We’ll Learn

Today, we’ll become Docker Detectives and learn how to:

1. Debug containers (peek inside the rooms)
2. Fix common errors (know what breaks and why)
3. Troubleshoot networks (check the hallways and pipes)
4. Read logs (find clues in the diary)

🔍 Container Debugging Techniques

The Detective’s Toolkit

Think of debugging like being a doctor for your containers. When a patient (container) feels sick, you need tools to check what’s wrong!

Technique 1: Peek Inside with docker exec

This is like opening the door and walking into the room to look around.

docker exec -it mycontainer /bin/sh

What this does:

• exec = “execute a command inside”
• -it = “let me type and see things”
• /bin/sh = “open a terminal”

Example:

# Check what files are inside
docker exec -it web ls /app

# See running processes
docker exec -it web ps aux

Technique 2: Watch What’s Happening with docker logs

Containers keep a diary of everything they do. Reading it tells you what went wrong!

docker logs mycontainer

Pro Tips:

# See only last 50 lines
docker logs --tail 50 mycontainer

# Watch live updates
docker logs -f mycontainer

Technique 3: Health Check with docker inspect

This is like an X-ray machine—you see EVERYTHING about the container.

docker inspect mycontainer

Example - Find the IP address:

docker inspect mycontainer | grep IPAddress

Technique 4: See Resource Usage

Is your container eating too much memory or CPU?

docker stats mycontainer

This shows live usage like a heartbeat monitor!

⚠️ Common Docker Errors (And How to Fix Them)

The “Usual Suspects” of Docker Problems

Let’s meet the villains and learn how to defeat them!

🚫 Error 1: “Container Exits Immediately”

What you see:

Container exited with code 0

Why it happens: The container’s main job finished instantly. Like a worker who shows up, sees nothing to do, and leaves!

The Fix:

# Keep it running with a command
docker run -d myimage tail -f /dev/null

# Or check what command it runs
docker inspect myimage --format='{{.Config.Cmd}}'

🚫 Error 2: “Port Already in Use”

What you see:

Bind for 0.0.0.0:8080 failed:
port is already allocated

Why it happens: Another container (or program) is already using that door!

The Fix:

# Find who's using the port
docker ps | grep 8080

# Or use a different port
docker run -p 8081:80 myimage

🚫 Error 3: “No Space Left on Device”

What you see:

no space left on device

Why it happens: Your disk is full of old images and containers!

The Fix:

# Clean up everything unused
docker system prune -a

# See what's taking space
docker system df

🚫 Error 4: “Image Not Found”

What you see:

Error: pull access denied
repository does not exist

Why it happens: You typed the name wrong, or the image doesn’t exist.

The Fix:

# Check spelling
docker search nginx

# Make sure you're logged in
docker login

🚫 Error 5: “Permission Denied”

What you see:

permission denied while connecting
to Docker daemon socket

Why it happens: You need special permission to talk to Docker!

The Fix:

# Add yourself to docker group
sudo usermod -aG docker $USER

# Then log out and back in!

🌐 Network Troubleshooting

When Containers Can’t Talk to Each Other

Imagine containers as houses in a neighborhood. They need roads (networks) to visit each other!

Step 1: Check What Networks Exist

docker network ls

You’ll see something like:

NETWORK ID     NAME      DRIVER
abc123         bridge    bridge
def456         host      host

Step 2: See Who’s Connected

docker network inspect bridge

This shows all containers on that network!

Step 3: Test Connection Between Containers

Can container A talk to container B?

# Get inside container A
docker exec -it containerA /bin/sh

# Try to ping container B
ping containerB

Step 4: Common Network Fixes

Problem: Containers can’t find each other by name

Solution: Put them on the same custom network!

# Create a network
docker network create mynetwork

# Run containers on it
docker run -d --network mynetwork \
  --name web nginx

docker run -d --network mynetwork \
  --name api myapi

# Now 'web' can reach 'api' by name!

Quick Network Diagram

graph TD
    A["Container: web"] --> N["mynetwork"]
    B["Container: api"] --> N
    C["Container: db"] --> N
    N --> D["Can talk by name!"]

📋 Log Analysis for Debugging

Reading the Container’s Diary

Logs are like a detective’s best friend—they tell you EXACTLY what happened and when!

Basic Log Commands

# See all logs
docker logs mycontainer

# See last 100 lines
docker logs --tail 100 mycontainer

# See logs from last 10 minutes
docker logs --since 10m mycontainer

# Watch logs live
docker logs -f mycontainer

# Show timestamps
docker logs -t mycontainer

Finding Errors in Logs

Use grep to search for problems:

# Find all errors
docker logs mycontainer 2>&1 | grep -i error

# Find warnings
docker logs mycontainer 2>&1 | grep -i warn

# Find crashes
docker logs mycontainer 2>&1 | grep -i fatal

Understanding Log Levels

Logs use these words to tell you how serious things are:

Example: Debugging a Crash

Your container keeps restarting. Here’s how to investigate:

# Step 1: See the logs
docker logs --tail 200 mycontainer

# Step 2: Look for the error
docker logs mycontainer 2>&1 | grep -i error

# Step 3: Check when it crashed
docker logs -t mycontainer | tail -20

Sample error you might find:

2024-01-15T10:30:45 ERROR:
  Cannot connect to database at db:5432

The clue: Container can’t reach the database. Check the network!

🎯 Quick Reference: The Debugging Checklist

When something goes wrong, follow these steps:

1. Is the container running?

   docker ps -a
   

2. What do the logs say?

   docker logs mycontainer
   

3. What’s the container’s status?

   docker inspect mycontainer
   

4. Can it reach the network?

   docker exec mycontainer ping google.com
   

5. Is there enough disk space?

   docker system df
   

🏆 You’re Now a Docker Detective!

You’ve learned to:

• ✅ Peek inside containers with exec
• ✅ Read the diary with logs
• ✅ Diagnose problems with inspect
• ✅ Fix common errors quickly
• ✅ Debug networks between containers
• ✅ Analyze logs like a pro

Remember: Every expert was once a beginner. The more you debug, the faster you’ll spot problems. You’ve got this! 🚀

“The best debugger is a calm mind and good logs.” – Every DevOps Engineer Ever