Docker simplifies deployment but introduces its own class of problems—networking issues, permission errors, resource constraints, and build failures. Quickly diagnosing and resolving Docker issues is essential for maintaining development velocity and production stability. This guide covers common Docker problems and solutions from a senior developer's perspective.
Why Troubleshooting Skills Matter
Docker troubleshooting enables:
- Faster Development: Unblock yourself and teammates quickly
- Production Reliability: Minimize downtime from container issues
- Resource Efficiency: Identify memory leaks and resource hogs
- Security: Understand and fix permission and networking problems
- Cost Optimization: Prevent runaway containers consuming resources
Diagnostic Commands
Check Docker Status
# Docker daemon status
sudo systemctl status docker
# Docker daemon logs
sudo journalctl -u docker.service
# Docker info
docker info
# Docker version
docker version
Container Diagnostics
# List all containers
docker ps -a
# Container logs
docker logs container_name
docker logs -f container_name # Follow/stream
docker logs --tail 100 container_name # Last 100 lines
docker logs --since 1h container_name # Last hour
# Container details
docker inspect container_name
# Resource usage
docker stats
docker stats container_name --no-stream
# Processes inside container
docker top container_name
# Execute diagnostic commands
docker exec -it container_name sh
docker exec container_name cat /etc/hosts
docker exec container_name env
Common Issues and Solutions
1. Container Won't Start
Symptom: Container exits immediately after starting.
# Check exit code
docker ps -a --filter "name=container_name"
# View logs
docker logs container_name
Common causes:
# Exit code 0: Process completed successfully (check if command is foreground)
# Fix: Ensure main process runs in the foreground
# Bad: CMD service nginx start
# Good: CMD ["nginx", "-g", "daemon off;"]
# Exit code 1: Application error
# Check logs for stack traces
# Exit code 137: Out of memory (OOM killed)
# Increase memory limit
docker run -m 512m my-app
# Exit code 139: Segmentation fault
# Check application for memory corruption issues
# Exit code 126: Permission denied
# Check file permissions and user
# Exit code 127: Command not found
# Verify CMD/ENTRYPOINT paths are correct
2. Cannot Connect to Docker Daemon
Symptom: Cannot connect to the Docker daemon at unix:///var/run/docker.sock
# Start Docker daemon
sudo systemctl start docker
# Check if current user is in the docker group
groups
# Add user to the docker group
sudo usermod -aG docker $USER
# Apply group change (or log out/log in)
newgrp docker
# Or
su - $USER
3. Container Networking Issues
Symptom: Containers can't communicate with each other or the internet.
# Check network configuration
docker network ls
docker network inspect bridge
# Test DNS resolution inside container
docker exec -it container_name nslookup google.com
# Test connectivity to other container
docker exec -it container1 ping container2
# Check firewall rules
sudo firewall-cmd --list-all
Solutions:
# Containers can't reach internet: Add DNS to daemon
# /etc/docker/daemon.json
{
"dns": ["8.8.8.8", "8.8.4.4"]
}
sudo systemctl restart docker
# Containers can't reach each other (CentOS/Firewalld)
sudo firewall-cmd --zone=docker --add-masquerade --permanent
sudo firewall-cmd --reload
sudo systemctl restart docker
# Create custom network for container communication
docker network create my-network
docker run --network my-network --name container1 image1
docker run --network my-network --name container2 image2
# Now containers can reach each other by name
4. Build Failures
Symptom: docker build fails with various errors.
# Permission denied reading directory
# Add directory to .dockerignore or fix permissions
echo "problematic-folder" >> .dockerignore
# Context too large (slow builds)
# Check what's being sent
du -sh .
# Add to .dockerignore:
node_modules
.git
*.log
# Can't find package/dependency
# Check if package name/version is correct
# Try building with no cache
docker build --no-cache -t my-app .
# apt-get update fails
# Network issue or outdated base image
# Try different base image or check network
docker build --network=host -t my-app .
5. Volume Permission Issues
Symptom: Application can't read/write to mounted volume.
# Check permissions
ls -la /host/path
docker exec container_name ls -la /container/path
# Check user inside container
docker exec container_name id
# Run container as specific user
docker run -u $(id -u):$(id -g) -v /host:/container image
# Fix ownership in Dockerfile
RUN chown -R appuser:appuser /app
USER appuser
6. Out of Disk Space
Symptom: no space left on device
# Check disk usage
docker system df
docker system df -v
# Clean up unused resources
docker system prune
# Aggressive cleanup (removes all unused images)
docker system prune -a
# Remove all volumes (DATA LOSS!)
docker system prune -a --volumes
# Remove specific old images
docker images --filter "dangling=true" -q | xargs docker rmi
# Remove containers older than 24h
docker container prune --filter "until=24h"
7. High Memory Usage
Symptom: Container using too much memory; system slowdown.
# Check memory usage
docker stats
# Set memory limits
docker run -m 512m --memory-swap 512m my-app
# In docker-compose.yml
services:
app:
deploy:
resources:
limits:
memory: 512M
reservations:
memory: 256M
8. Port Already in Use
Symptom: Bind for 0.0.0.0:80 failed: port is already allocated
# Find what's using the port
sudo lsof -i :80
sudo netstat -tulpn | grep :80
# Find container using the port
docker ps --filter "publish=80"
# Stop the container
docker stop container_name
# Or use a different port
docker run -p 8080:80 nginx
9. DNS Resolution Fails
Symptom: Temporary failure resolving 'deb.debian.org' during build.
# Add DNS to Docker daemon
# /etc/docker/daemon.json
{
"dns": ["1.1.1.1", "8.8.8.8"]
}
sudo systemctl restart docker
# Or build with host networking
docker build --network=host -t my-app .
10. SSL Certificate Issues
Symptom: self-signed certificate in certificate chain
# For Node.js in development (NOT for production!)
docker run -e NODE_TLS_REJECT_UNAUTHORIZED=0 my-node-app
# Install custom CA certificate in Dockerfile
COPY my-ca.crt /usr/local/share/ca-certificates/
RUN update-ca-certificates
Docker Compose Issues
Containers Not Communicating
# Ensure containers are on the same network
services:
web:
networks:
- app-network
db:
networks:
- app-network
networks:
app-network:
driver: bridge
Environment Variables Not Loading
# Check .env file location (same directory as docker-compose.yml)
# Check variable syntax in docker-compose.yml
services:
app:
environment:
- DATABASE_URL=${DATABASE_URL} # From .env
- STATIC_VALUE=hardcoded # Literal value
Volumes Not Syncing
# Remove volumes and recreate
docker-compose down -v
docker-compose up -d
# Check volume mount path
docker-compose config # Shows resolved configuration
Platform-Specific Issues
macOS Docker Desktop
# Slow file sync with volumes
# Use :cached or :delegated flags
volumes:
- ./src:/app/src:cached
# Out of disk space
# Docker Desktop -> Preferences -> Resources -> Disk
Linux with SELinux
# Permission denied on volumes
# Add :z or :Z flag
docker run -v /host:/container:z image
# Or disable SELinux for Docker
# Not recommended for production
Apple Silicon (M1/M2)
# Image not compatible
# Specify platform
services:
app:
platform: linux/amd64
image: some-x86-only-image
Key Takeaways
- Check logs first:
docker logs reveals most issues - Inspect everything:
docker inspect shows configuration details - Network issues are common: Custom networks solve most connectivity problems
- Clean up regularly: Prevent disk space issues with
docker system prune - Resource limits matter: Set memory limits to prevent OOM issues
- Permissions are tricky: Match container user with host file ownership
Docker troubleshooting becomes intuitive with practice—most issues fall into predictable categories with known solutions.
