docker-local-troubleshoot

Diagnose and fix docker-local issues - container failures, connectivity problems, port conflicts, and configuration errors

⭐3stars🔀0forks📁View on GitHub🕐Updated Jan 7, 2026

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.
namedocker-local-troubleshoot
descriptionDiagnose 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:

  1. Stop and ask the user if they want to install it
  2. If yes, install via: composer global require mwguerra/docker-local
  3. Add to PATH: export PATH="$HOME/.composer/vendor/bin:$PATH"
  4. Initialize: docker-local init
  5. Verify: which docker-local && docker-local --version

Diagnostic Process

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:

  1. Root Cause: What caused the issue
  2. Solution: Commands that fix it
  3. Prevention: How to avoid in future
  4. 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