---
name: docker-container-debugger
description: "Gets a crashing, hanging, or misbehaving container diagnosed with an ordered command sequence: what to run, why, and what a healthy versus faulty result looks like at each step. Use when a running container crashes, restarts, hangs, or cannot reach its dependencies and the user needs the commands to find out why. Do not use for assessing an image for vulnerabilities before deployment, or shrinking an image. Related topics: coding, docker."
---

# Docker Container Debugger

Gets a crashing, hanging, or misbehaving container diagnosed with an ordered command sequence: what to run, why, and what a healthy versus faulty result looks like at each step.

## When to use

Use this skill when a running container crashes, restarts, hangs, or cannot reach its dependencies and the user needs the commands to find out why. Do not use it for assessing an image for vulnerabilities before deployment, or shrinking an image.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Order the checks from outside in: state and exit code, logs for the timeframe, resources and OOM, networking, filesystem and permissions, then in-container processes.
3. Write each check as the exact command for the chosen runtime with its purpose, the healthy result, and what a faulty result indicates.
4. Substitute tooling for minimal base images (busybox or a debug container) and remove commands the access level cannot run.
5. Name the two most likely causes for the symptom and point to the step that confirms each.

## Inputs

- **Container ID or name** (free text, e.g. "api-worker-1")
- **Problem symptom** (longer free text)
- **Base image OS** (choose one: Alpine, Ubuntu, Debian, CentOS, Distroless, Other)
- **Access level** (choose one: root, non-root)
- **Log locations to inspect** (choose any: Container stdout and stderr, /var/log/app.log, /var/log/syslog, Orchestrator logs, Custom path)
- **Issue timeframe** (choose one: last 5 minutes, last hour, last day, unknown)
- **Runtime** (choose one: Docker CLI, Docker Compose, Kubernetes, ECS, Other)

## Output

A numbered Markdown list, one step each with the command, a one-line purpose, the expected healthy result, and the faulty-result interpretation, followed by the two most likely causes and their confirming steps.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Docker Container Debugger

Give me an ordered troubleshooting sequence for this container.

- Container ID or name: {{Container ID or name}}
- Problem symptom: {{Problem symptom}}
- Base image OS: {{Base image OS}}
- Access level: {{Access level}}
- Log locations to inspect: {{Log locations to inspect}}
- Issue timeframe: {{Issue timeframe}}
- Runtime: {{Runtime}}

Order the sequence from outside the container inward, since most problems show up before you need a shell: container state and exit code (docker inspect, docker ps -a), then logs for the timeframe (docker logs --since), then resource limits and OOM kills (docker stats, inspect State.OOMKilled), then networking (port bindings, DNS from inside, connectivity to dependencies), then filesystem and permissions (mounts, ownership, a non-root user writing to a root-owned path), and only then process-level checks inside the container. For each step give the exact command adjusted to the runtime (kubectl or docker compose equivalents when relevant), one line on its purpose, what a healthy result looks like, and what a faulty result points to. Account for the base OS: Alpine and distroless images lack bash, curl, and ps, so give the busybox or debug-container alternative. Respect the access level by avoiding commands that need root when the user does not have it. End with the two most likely causes given the symptom and the step that confirms each.

## Pitfalls

- Starting with docker exec when the container exits immediately; the exit code and logs answer most crashes without a shell.
- Giving bash and curl commands for an Alpine or distroless image where neither exists.
- Reading logs without --since, so the relevant error is buried under a day of healthy output.
