docker-troubleshoot

Diagnose container failures, networking issues, permissions, and port conflicts

⭐3stars🔀0forks📁View on GitHub🕐Updated Dec 20, 2025⬇️1downloads

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.
namedocker-troubleshoot
descriptionDiagnose 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.md for common issues
  • 15-port-conflicts.md for port problems
  • 16-restart-strategies.md for 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

  1. Check if container is running: docker compose ps
  2. Check logs: docker compose logs servicename
  3. Check network: docker network ls
  4. Check volumes: docker volume ls
  5. Check resources: docker stats
  6. Validate config: docker compose config
  7. 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