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

docker login

docker compose pull