Skip to content

commandDevOps and clouddocker

Debug Container

Finds why a Docker container exits, restarts or misbehaves by reading its logs, exit code, config and Dockerfile together.

npx workspacetemplates add debug-container --tool claude-code

Writes 1 file to .claude/commands/

.claude/commands/debug-container.md14 lines · 1.4 KBFile
---
description: Finds why a Docker container exits, restarts or misbehaves by reading its logs, exit code, config and Dockerfile together.
argument-hint: "[container name, id or compose service]"
---

Debug this container: $ARGUMENTS (container name or id, or a compose service; if empty, check the most recently exited one).

1. Inspect state with read-only commands: `docker ps -a --filter "name=..."`, `docker inspect --format '{{.State.ExitCode}} {{.State.OOMKilled}} {{.State.Error}}' <c>`, and `docker logs --tail 100 <c>`.
2. Read the exit code: 0 means the main process finished, 1 an app error, 125 to 127 a bad command or missing binary, 137 killed (memory limit or manual stop), 139 a crash, 143 stopped by SIGTERM.
3. Compare the entrypoint and CMD from `docker inspect` with the Dockerfile. Look for shell versus exec form, missing executable bits, wrong WORKDIR, a process that daemonizes and exits, and files removed by .dockerignore.
4. Check configuration: environment variables, mounted volumes, network and published ports, healthcheck result, and depends_on ordering in the compose file.
5. If the container is running, you may use `docker exec <c> ls` or `env` to look inside. Do not change anything.

Report the most likely cause first, the evidence from each step, and the exact fix (a Dockerfile or compose edit). Ask before editing files, restarting, or running `docker rm`.

What it does

A container that dies seconds after start rarely says why. The clue is spread across the exit code, the last log lines, the entrypoint, the environment and the file layout inside the image.

This command gathers those clues with read-only Docker commands, matches them against the Dockerfile and compose file, and names the likely cause with the evidence. It does not stop, remove or rebuild anything without your answer.

Example

you › /debug-container web

agent › Exit code 127, log: "exec ./start.sh: no such file or directory". Cause: start.sh has Windows line endings (CRLF), so the interpreter path fails. Fix: convert the file to LF and add a .gitattributes rule. Apply the edit?

Questions

Will it delete or restart my containers?
No. It uses read-only inspection and asks before any change, including a restart.
What if the image is not on my machine?
Then it can only reason from the Dockerfile and compose files, and it tells you which checks it could not run.
  • Deploy Checklist

    CommandDevOps and cloud

    Free
  • Dockerize

    Commanddocker

    Free
  • Document Env Vars

    CommandDevOps and cloud

    Free
  • Review Terraform Plan

    Commandterraform

    Free