Docker Debugging Skill

Master container debugging and troubleshooting for development and production issues.

Purpose

Diagnose and resolve container issues including crashes, performance problems, networking failures, and resource constraints.

Parameters

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | container | string | No | - | Container name/ID | | issue_type | enum | No | - | crash/network/resource/health | | verbose | boolean | No | false | Detailed output |

Debugging Commands

Container Logs

# Last 100 lines
docker logs --tail 100 <container>

# Follow logs
docker logs -f <container>

# With timestamps
docker logs -t <container>

# Specific time range
docker logs --since 1h --until 30m <container>

Interactive Debugging

# Execute shell in running container
docker exec -it <container> /bin/sh

# As root (for debugging)
docker exec -u 0 -it <container> /bin/sh

# Run command
docker exec <container> ps aux

Container Inspection

# Full inspection
docker inspect <container>

# Specific fields
docker inspect --format='{{.State.Status}}' <container>
docker inspect --format='{{.State.Health.Status}}' <container>
docker inspect --format='{{json .NetworkSettings}}' <container>

Issue Diagnosis

Container Won't Start

# Check exit code
docker inspect --format='{{.State.ExitCode}}' <container>

# View last logs
docker logs --tail 50 <container>

# Check events
docker events --filter 'container=<name>' --since 1h

Exit Code Reference

| Code | Meaning | Action | |------|---------|--------| | 0 | Success | Normal exit | | 1 | General error | Check logs | | 137 | OOMKilled | Increase memory | | 139 | Segfault | Check app code | | 143 | SIGTERM | Graceful shutdown |

Health Check Failures

# Check health status
docker inspect --format='{{json .State.Health}}' <container>

# View health logs
docker inspect --format='{{range .State.Health.Log}}{{.Output}}{{end}}' <container>

# Manually test health
docker exec <container> curl -f http://localhost/health

Resource Issues

# Live stats
docker stats <container>

# Formatted output
docker stats --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.NetIO}}"

# Check limits
docker inspect --format='{{.HostConfig.Memory}}' <container>

Network Issues

# Check network
docker network inspect <network>

# Test DNS
docker exec <container> nslookup <service>

# Test connectivity
docker exec <container> ping -c 3 <target>
docker exec <container> curl http://<service>:port

# View ports
docker port <container>

Troubleshooting Flowchart

Container Issue?
│
├─ Won't Start
│  ├─ Check logs: docker logs <c>
│  ├─ Check exit code: docker inspect
│  └─ Verify image: docker pull
│
├─ Unhealthy
│  ├─ Check health logs
│  ├─ Test health endpoint manually
│  └─ Increase start_period
│
├─ High Resource
│  ├─ Check stats: docker stats
│  ├─ Increase limits
│  └─ Profile application
│
└─ Network Failed
   ├─ Check DNS: nslookup
   ├─ Check connectivity: ping/curl
   └─ Verify network membership

Debug Container

# Run debug container in same network
docker run --rm -it --network <network> \
  nicolaka/netshoot

# Available tools: curl, dig, nmap, tcpdump, etc.

Error Handling

Common Errors

| Error | Cause | Solution | |-------|-------|----------| | container not found | Wrong name/ID | Use docker ps -a | | exec failed | Container stopped | Start container first | | no such file | Missing binary | Use correct image |

Usage

Skill("docker-debugging")

Assets

• assets/debug-commands.yaml - Command reference
• scripts/container-health-check.sh - Health check script

Related Skills

• docker-production
• docker-networking