docker-troubleshoot
Diagnose container failures, networking issues, permissions, and port conflicts
When & Why to Use This Skill
The Docker Troubleshooting skill is a comprehensive diagnostic toolkit designed to identify and resolve containerization issues. It streamlines the debugging process for container failures, networking hurdles, permission conflicts, and resource management, helping developers and DevOps engineers maintain stable and efficient Docker environments through automated diagnostic workflows.
Use Cases
- Diagnosing container startup failures by analyzing exit codes and logs to pinpoint configuration errors or missing dependencies.
- Resolving port conflicts by identifying active host processes and reconfiguring Docker Compose port mappings.
- Fixing filesystem 'Permission Denied' errors by auditing container user IDs and adjusting volume ownership settings.
- Troubleshooting inter-container connectivity issues within Docker networks using inspection and network lookup tools.
- Optimizing system resources and build performance by identifying and pruning unused volumes, images, and build caches.
| name | docker-troubleshoot |
|---|---|
| description | Diagnose container failures, networking issues, permissions, and port conflicts |
Docker Troubleshooting Skill
Overview
This skill helps diagnose and resolve common Docker issues:
- Container startup failures
- Networking problems
- Permission errors
- Port conflicts
- Data persistence issues
- Health check failures
Process
1. Consult Documentation
Read relevant documentation:
17-troubleshooting.mdfor common issues15-port-conflicts.mdfor port problems16-restart-strategies.mdfor restart issues
2. Diagnose Issue
Gather information:
# Check container status
docker compose ps -a
# View logs
docker compose logs servicename
# Check configuration
docker compose config
# Inspect container
docker inspect containername
3. Apply Solution
Common Issues and Solutions
Container Won't Start
Diagnosis:
docker compose logs servicename
docker inspect --format='{{.State.ExitCode}}' containername
Solutions:
- Check logs for error messages
- Verify configuration syntax
- Check dependencies are running
- Verify image exists
Port Already in Use
Diagnosis:
lsof -i :3000
# or
netstat -tulpn | grep 3000
Solutions:
# Kill process
kill $(lsof -t -i:3000)
# Or change port in compose
ports:
- "3001:3000"
Permission Denied
Diagnosis:
docker compose exec app ls -la /app/data
Solutions:
# Fix in compose
services:
app:
user: "1000:1000"
# Or fix in container
docker compose exec -u root app chown -R appuser:appgroup /app/data
Data Disappearing
Diagnosis:
docker volume ls
docker compose config | grep -A5 "volumes:"
Solutions:
# Use named volumes instead of anonymous
volumes:
- postgres_data:/var/lib/postgresql/data # Named (persists)
# NOT: - /var/lib/postgresql/data # Anonymous (deleted)
Container Can't Reach Other Container
Diagnosis:
docker network inspect networkname
docker compose exec app ping db
docker compose exec app nslookup db
Solutions:
# Ensure same network
services:
app:
networks:
- backend
db:
networks:
- backend
networks:
backend:
Health Check Failing
Diagnosis:
docker inspect --format='{{json .State.Health}}' containername | jq
Solutions:
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 40s # Give time to start
Out of Disk Space
Diagnosis:
docker system df
docker system df -v
Solutions:
# Clean unused resources
docker system prune -a --volumes
Build Cache Issues
Solutions:
docker compose build --no-cache
docker builder prune -a
Debugging Commands
# Shell into running container
docker compose exec app sh
# Shell into failed container
docker compose run --entrypoint sh app
# View resource usage
docker stats
# View container processes
docker compose top
# View real-time events
docker events
# Copy files from container
docker compose cp app:/app/logs ./logs
Quick Diagnostic Checklist
- Check if container is running:
docker compose ps - Check logs:
docker compose logs servicename - Check network:
docker network ls - Check volumes:
docker volume ls - Check resources:
docker stats - Validate config:
docker compose config - Check disk space:
docker system df
Error Messages Reference
| Error | Cause | Solution |
|---|---|---|
| "port is already allocated" | Port in use | Kill process or change port |
| "network not found" | Missing network | Create network or check name |
| "volume not found" | Missing volume | Create volume or check name |
| "no such service" | Service name typo | Check compose.yaml |
| "unauthorized" | Auth issue | docker login |
| "image not found" | Missing image | docker compose pull |
| "permission denied" | File permissions | Fix ownership/permissions |
| "out of memory" | Memory limit | Increase limit or optimize app |