Common Issues: Problems You'll Face and How to Fix Them
Docker works. Until it doesn't. Problems happen. But they're fixable. That's what this is about.
🎯 The Big Picture​
Think of common issues like car problems. Engine won't start (container won't run). Out of gas (out of disk space). Flat tire (network issue). Common problems. Known solutions. That's common issues.
Common issues are problems everyone faces. Known solutions. Fixable. This is your troubleshooting guide.
Issue 1: Container Won't Start​
Problem:
docker run nginx
# Error: Cannot connect to the Docker daemon
Solution:
# Check if Docker is running
docker ps
# Start Docker daemon
# macOS: Open Docker Desktop
# Linux: sudo systemctl start docker
# Windows: Start Docker Desktop
Why: Docker daemon not running. Start it.
Think of it as: Car won't start. Check if engine is on.
Issue 2: Out of Disk Space​
Problem:
docker build -t my-app .
# Error: no space left on device
Solution:
# Check disk usage
docker system df
# Clean up
docker system prune -a
# Remove unused volumes
docker volume prune
# Remove unused images
docker image prune -a
Why: Disk full. Clean up unused resources.
Think of it as: Out of gas. Refuel (clean up).
Issue 3: Port Already in Use​
Problem:
docker run -p 80:80 nginx
# Error: bind: address already in use
Solution:
# Find what's using the port
# macOS/Linux
lsof -i :80
# Windows
netstat -ano | findstr :80
# Stop the process or use different port
docker run -p 8080:80 nginx
Why: Port already in use. Free it or use different port.
Think of it as: Parking spot taken. Find another spot.
Issue 4: Image Pull Fails​
Problem:
docker pull nginx
# Error: pull access denied
Solution:
# Login to registry
docker login
# Check image name
docker pull nginx:alpine
# Use public registry
docker pull docker.io/nginx:alpine
Why: Authentication issue or wrong image name.
Think of it as: Access denied. Check credentials.
Issue 5: Container Exits Immediately​
Problem:
docker run nginx
# Container exits immediately
Solution:
# Check logs
docker logs container-name
# Run interactively
docker run -it nginx sh
# Check if process is running
docker exec container-name ps aux
Why: Process exits. Check logs. Fix issue.
Think of it as: Car starts then stops. Check what's wrong.
The Car Problems Analogy​
Think of common issues like car problems:
Container won't start: Engine won't start Out of disk space: Out of gas Port in use: Parking spot taken Image pull fails: Access denied Container exits: Car starts then stops
Once you see it this way, troubleshooting makes perfect sense.
Issue 6: Permission Denied​
Problem:
docker run -v /data:/data nginx
# Error: permission denied
Solution:
# Fix permissions
sudo chown -R $USER:$USER /data
# Or use named volume
docker volume create data
docker run -v data:/data nginx
Why: Permission issue. Fix permissions or use volumes.
Think of it as: Locked door. Get key (permissions).
Issue 7: Network Issues​
Problem:
docker run app
# Cannot connect to database
Solution:
# Check network
docker network ls
# Connect to same network
docker network create app-network
docker run --network app-network app
docker run --network app-network db
# Use service names
# app can connect to db using hostname "db"
Why: Containers not on same network. Connect them.
Think of it as: Can't call friend. Check if on same network.
Issue 8: Build Fails​
Problem:
docker build -t my-app .
# Error: failed to solve
Solution:
# Check Dockerfile syntax
docker build --no-cache -t my-app .
# Check build context
docker build -f Dockerfile -t my-app .
# Check logs
docker build --progress=plain -t my-app .
Why: Dockerfile issue or build context problem.
Think of it as: Recipe wrong. Check recipe (Dockerfile).
Real-World Example: Complete Troubleshooting​
Problem: Container keeps restarting
Step 1: Check status
docker ps -a
# See container status
Step 2: Check logs
docker logs container-name
# See error messages
Step 3: Check health
docker inspect container-name | grep Health
# See health status
Step 4: Fix issue
# Based on logs, fix the problem
# Common fixes:
# - Fix application code
# - Fix environment variables
# - Fix volume mounts
# - Fix network configuration
Step 5: Restart
docker restart container-name
# Or rebuild and run
That's troubleshooting. Systematic. Effective.
Best Practices​
1. Check Logs First​
Always check logs:
docker logs container-name
Why: Logs show the problem.
2. Use docker inspect​
Inspect everything:
docker inspect container-name
docker inspect image-name
docker inspect network-name
Why: See configuration. Find issues.
3. Test Incrementally​
Test step by step:
- Test image
- Test container
- Test network
- Test volumes
Why: Isolate the problem.
4. Use docker exec​
Debug running containers:
docker exec -it container-name sh
Why: See what's happening inside.
5. Clean Up Regularly​
Prevent issues:
docker system prune -a
Why: Prevent disk space issues.
My Take: Troubleshooting Strategy​
Here's what I do:
When problem occurs:
- Check logs
- Inspect container
- Check resources
- Test incrementally
- Fix and verify
Prevention:
- Clean up regularly
- Monitor resources
- Use health checks
- Document issues
The key: Systematic approach. Check logs. Inspect. Test. Fix.
Memory Tip: The Car Problems Analogy​
Common issues = Car problems
Container won't start: Engine won't start Out of space: Out of gas Port in use: Spot taken Permission denied: Locked door
Once you see it this way, troubleshooting makes perfect sense.
Common Mistakes​
- Not checking logs: Don't know the problem
- Not inspecting: Don't see configuration
- Giving up too soon: Problems are fixable
- Not cleaning up: Disk space issues
- Not documenting: Repeat same mistakes
Hands-On Exercise: Troubleshoot​
1. Create a problem:
# Run container with wrong port
docker run -p 9999:80 nginx
2. Check if it works:
curl http://localhost:9999
3. Create another problem:
# Run container that exits
docker run alpine
4. Check why:
docker ps -a
docker logs <container-id>
5. Fix it:
# Run with command
docker run alpine sleep 60
That's troubleshooting. Practice. Learn.
Key Takeaways​
- Check logs first - Logs show the problem
- Use docker inspect - See configuration
- Test incrementally - Isolate the problem
- Use docker exec - Debug inside container
- Clean up regularly - Prevent issues
- Most problems are fixable - Don't give up
What's Next?​
Now that you understand common issues, let's learn about debugging techniques. Next: Debugging Techniques.
Remember: Common issues are like car problems. Known problems. Known solutions. Check logs. Inspect. Test. Fix. Most problems are fixable.