docker-local-troubleshoot
Diagnose and fix docker-local issues - container failures, connectivity problems, port conflicts, and configuration errors
When & Why to Use This Skill
The Docker-Local Troubleshooting skill is a specialized diagnostic assistant designed to streamline local development by identifying and resolving common Docker environment issues. It provides automated fixes for container failures, port conflicts, and network misconfigurations, acting as an intelligent runbook for the mwguerra/docker-local toolset to minimize downtime for developers.
Use Cases
- Automated Environment Repair: Running comprehensive diagnostic checks to automatically fix Docker daemon issues, stopped containers, and missing system configurations.
- Port Conflict Management: Identifying and terminating processes occupying essential ports like 80, 443, or 3306 to allow Docker services to bind successfully.
- Network and DNS Troubleshooting: Resolving connectivity issues for *.test domains and fixing SSL/certificate errors to ensure local web projects are accessible.
- Container Crash Analysis: Diagnosing specific exit codes (e.g., OOM kills or application errors) and providing targeted recovery steps or resource adjustments.
- Full Environment Reset: Executing a safe, multi-step cleanup of Docker volumes, networks, and configurations to restore a functional state when standard fixes fail.
| name | docker-local-troubleshoot |
|---|---|
| description | Diagnose and fix docker-local issues - container failures, connectivity problems, port conflicts, and configuration errors |
Docker-Local Troubleshooting Skill
Overview
This skill helps diagnose and fix common docker-local issues including:
- Container failures and crashes
- Port conflicts
- Permission errors
- Network connectivity problems
- Database connection issues
- DNS and SSL problems
Activation
Use this skill when:
- User reports Docker errors
- Services won't start
- Projects aren't accessible
- Database connections fail
- SSL/certificate issues
- General "it's not working" complaints
MANDATORY: Prerequisite Check
Before ANY docker-local command, verify installation:
which docker-local > /dev/null 2>&1
If docker-local is NOT found:
- Stop and ask the user if they want to install it
- If yes, install via:
composer global require mwguerra/docker-local - Add to PATH:
export PATH="$HOME/.composer/vendor/bin:$PATH" - Initialize:
docker-local init - Verify:
which docker-local && docker-local --version
Diagnostic Process
1. Quick Fix (Recommended First Step)
Use the fix command for automatic diagnosis and resolution:
# Run all checks and auto-fix what's possible
docker-local fix
# Target specific areas
docker-local fix --dns # Only check/fix DNS issues
docker-local fix --docker # Only check/fix Docker daemon
docker-local fix --services # Only check/fix container services
docker-local fix --hosts # Only check/fix /etc/hosts
# Additional options
docker-local fix --verbose # Show detailed diagnostic info
docker-local fix --dry-run # Show what would be fixed without making changes
The fix command automatically detects and resolves:
- Docker daemon not running
- Stopped containers
- Missing systemd-resolved configuration for *.test DNS
- Missing dnsmasq configuration
- /etc/hosts not configured
2. Gather Additional Information
# Check docker-local status
docker-local status
# View recent logs
docker-local logs --tail=50
# Check Docker system
docker info
docker system df
3. Common Issue Patterns
Docker Not Running
Error: Docker is not running
Diagnosis:
docker info 2>&1
systemctl status docker # Linux
Fix:
# Linux
sudo systemctl start docker
# macOS
open -a Docker
# Windows (WSL2)
# Start Docker Desktop from Windows Start Menu
Port Already in Use
Error: Port 3306 already in use
Diagnosis:
# Find what's using the port
lsof -i :3306
netstat -tulpn | grep 3306
# Common ports to check:
# 80, 443 - Traefik/HTTP
# 3306 - MySQL
# 5432 - PostgreSQL
# 6379 - Redis
# 9000, 9001 - MinIO
# 1025, 8025 - Mailpit
Fix:
# Kill the process using the port
kill $(lsof -t -i:3306)
# Or change port in config
# Edit ~/.config/docker-local/config.json
Container Won't Start
Container php: Exited (1)
Diagnosis:
# Check logs for the failing container
docker-local logs php
# Check exit code
docker inspect --format='{{.State.ExitCode}}' php
# Exit codes:
# 0 - Normal stop
# 1 - Application error
# 137 - Out of memory (OOM killed)
# 139 - Segmentation fault
Fix based on exit code:
# Exit 1 - Check application logs
docker-local logs php --tail=100
# Exit 137 - Increase Docker memory
# Docker Desktop > Settings > Resources > Memory
# Restart the container
docker-local restart
Permission Denied
Error: Permission denied
Diagnosis:
# Check user permissions
id
groups
# Check project permissions
ls -la ~/projects/
# Check Docker socket
ls -la /var/run/docker.sock
Fix:
# Linux: Add user to docker group
sudo usermod -aG docker $USER
newgrp docker
# Fix project permissions
sudo chown -R $USER:$USER ~/projects
# Fix socket permissions (temporary)
sudo chmod 666 /var/run/docker.sock
Cannot Connect to Database
SQLSTATE[HY000] [2002] Connection refused
Diagnosis:
# Check if database container is running
docker-local status
# Check database logs
docker-local logs mysql
docker-local logs postgres
# Test connection from inside container
docker exec php php -r "new PDO('mysql:host=mysql;dbname=laravel', 'laravel', 'secret');"
Fix:
# Ensure services are running
docker-local up
# Wait for database to be ready (health check)
docker-local status
# Check .env has correct host (mysql, not localhost)
# DB_HOST=mysql
DNS Not Resolving (*.test domains)
Could not resolve host: myapp.test
Diagnosis:
# Check if DNS is configured
ping myapp.test
# Check /etc/hosts
cat /etc/hosts | grep test
# Check dnsmasq (if used)
systemctl status dnsmasq # Linux
Fix:
# Option 1: Setup DNS (recommended)
sudo docker-local setup:dns
# Option 2: Add to /etc/hosts
sudo docker-local setup:hosts
# Option 3: Manual hosts entry
echo "127.0.0.1 myapp.test" | sudo tee -a /etc/hosts
SSL Certificate Issues
SSL certificate problem: unable to get local issuer certificate
Diagnosis:
# Check SSL certificate status
docker-local ssl:status
# Check certificates exist
ls -la ~/.config/docker-local/certs/
# Check certificate validity
openssl x509 -in ~/.config/docker-local/certs/localhost.pem -noout -dates
# Test HTTPS
curl -vk https://localhost 2>&1 | head -20
Fix:
# Regenerate SSL certificates with mkcert
docker-local ssl:regenerate
# Or regenerate during init
docker-local init --certs
# Trust the certificate (browser)
# Import ~/.config/docker-local/certs/localhost.pem
# For mkcert users
mkcert -install
Projects Not Visible
No projects found in ~/projects
Diagnosis:
# Check projects directory
ls -la ~/projects/
# Check config
docker-local config | grep projects_path
# Verify project structure
ls -la ~/projects/myapp/artisan
Fix:
# Ensure projects are in correct location
mv /path/to/myapp ~/projects/
# Or update config
# Edit ~/.config/docker-local/config.json
# Change projects_path
4. Full Reset Procedure
If all else fails, perform a complete reset:
# Stop everything
docker-local down
# Remove all Docker resources
docker system prune -af
docker volume prune -f
docker network prune -f
# Remove docker-local config (backup first)
mv ~/.config/docker-local ~/.config/docker-local.backup
# Reinitialize
docker-local init
# Restart
docker-local up
# Restore projects (they're safe in ~/projects)
docker-local list
5. Useful Debugging Commands
# Shell into PHP container
docker-local shell
# Real-time Docker events
docker events
# Container resource usage
docker stats --no-stream
# Network inspection
docker network inspect laravel-dev
# Volume inspection
docker volume ls
docker volume inspect mysql_data
# Compose configuration check
docker compose -f ~/.config/docker-local/docker-compose.yml config
Report Format
After troubleshooting, provide:
- Root Cause: What caused the issue
- Solution: Commands that fix it
- Prevention: How to avoid in future
- Verification: How to confirm it's fixed
Issue: MySQL container not starting
Root Cause: Port 3306 already in use by local MySQL installation
Solution:
sudo systemctl stop mysql # Stop local MySQL
docker-local up # Start docker-local
Prevention:
- Use docker-local consistently
- Or change MySQL port in ~/.config/docker-local/config.json
Verification:
docker-local status # Should show mysql: Running
docker-local db:mysql # Should open MySQL CLI
$ARGUMENTS