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