debug-docker_skill

Overview

This skill helps you debug Docker containers, images, networks, and volumes using a systematic four-phase methodology. It gives actionable commands and patterns to quickly assess problems, analyze logs, perform interactive investigation, and run deep analysis for complex failures. The guidance covers common exit codes, OOM kills, build failures, networking, volume mounts, permission errors, and platform-specific tips for Windows, Mac, and Linux.

How this skill works

Start with a quick assessment to collect immediate context (status, recent logs, exit codes, health). Move to targeted log analysis and Docker events to identify trends and triggers. Use interactive techniques (docker exec, docker debug, sidecar containers) to inspect runtime state, network, and filesystems. For persistent or complex issues, run resource monitoring, inspect image layers, export filesystems, and perform deep analysis with system logs and layered debugging.

When to use it

• Container exits unexpectedly or immediately after start
• High memory use or containers OOM-killed (exit 137)
• Image build failures or caching-related errors
• Networking failures between containers or external hosts
• Volume mount problems or permission denied on files
• Docker Desktop fails to start on Windows, Mac, or Linux

Best practices

• Follow the four-phase workflow: quick assessment, log analysis, interactive investigation, deep analysis
• Reproduce the issue in a disposable container (tail -f /dev/null or sleep infinity) before modifying production
• Use minimal debug sidecars (netshoot, busybox) when base images lack tools
• Inspect exit codes first and map them to common causes (127 = missing binary, 137 = OOM)
• Monitor resources (docker stats) and check daemon logs (journalctl or Docker Desktop logs) for system-level causes
• Verify host paths, UID/GID mappings, and SELinux labels when mounts or permissions fail

Example use cases

• Diagnose a web service that starts then exits: check logs, inspect entrypoint, override entrypoint to a shell
• Investigate sporadic OOM kills: inspect HostConfig.Memory, run docker stats, and increase memory limit or optimize app
• Fix a failing Dockerfile layer: build --progress=plain, --no-cache, or run the last successful layer interactively
• Resolve inter-container networking issues: docker network inspect, run netshoot in the target network and test DNS/HTTP
• Troubleshoot Docker Desktop startup: check virtualization, disk space, reset Docker Desktop data, or review daemon logs