.env file is passed via env_file in docker-compose
Common Failures
Symptom
Likely Cause
Fix
ModuleNotFoundError
Dependency missing in pyproject.toml
uv add <package> in the example, rebuild
Connection refused on port 8000
App not binding to 0.0.0.0
Set --host 0.0.0.0 in uvicorn command
Container restarts in loop
Crash on startup (missing env var)
Check .env file, compare with .env.example
network X not found
Compose network not created
Run docker compose down then up again
Build fails at uv sync
Lock file out of sync
Run uv lock locally first, then rebuild
Shell Commands (PowerShell)
# Build and run from example directory
docker compose up --build
# Rebuild single service
docker compose up --build agent
# View logs for a service
docker compose logs -f agent
# Full reset (remove containers, networks, volumes)
docker compose down -v
1---2name: ksopyla-agent-patterns-lab-docker-debugger3description: Docker Debugger4---56# Docker Debugger78## When to Use910Trigger this skill when:11- `docker compose up --build` fails or a container exits unexpectedly12- An agent service can't reach another service (network/DNS issues)13- Debugging multi-container setups in Patterns 05+14- Investigating image build failures with the base Dockerfile1516## Available MCP Tools1718Use the Docker MCP (`project-0-agent-patterns-lab-docker`) for inspection:1920| Tool | Purpose |21|------|---------|22| `list_containers` | See running/stopped containers and their status |23| `fetch_container_logs` | Read stdout/stderr from a specific container |24| `list_images` | Check built images and tags |25| `list_networks` | Inspect Docker networks for multi-service setups |26| `list_volumes` | Check persistent volumes (PostgreSQL, etc.) |27| `start_container` / `stop_container` | Control individual containers |28| `recreate_container` | Rebuild and restart a single container |2930## Diagnostic Workflow31321. **Check container status**33 - Call `list_containers` to see which containers are running, exited, or restarting34 - Note exit codes: `0` = clean stop, `1` = app error, `137` = OOM killed35362. **Read logs for the failing container**37 - Call `fetch_container_logs` with the container name38 - Look for: import errors, missing env vars, port conflicts, connection refused39403. **Verify network connectivity** (multi-service)41 - Call `list_networks` to confirm all services share a network42 - Service DNS names match the `services:` keys in `docker-compose.yml`43 - Common fix: services on different networks can't reach each other44454. **Check image build**46 - Call `list_images` to verify the image was built47 - If missing, the build stage likely failed -- re-read build logs48495. **Fix and rebuild**50 - Fix the issue in code or config51 - Run `docker compose up --build` to rebuild5253## Project-Specific Build Context5455All examples use the base Dockerfile at `infra/docker/base/Dockerfile.agent`:56- Build context is always the repo root (`../..` from the example)57- Compose sets `PACKAGE_NAME`, `EXAMPLE_PYPROJECT`, and `EXAMPLE_SRC` for that example58- Multi-stage build: `builder` installs deps, `runtime` copies artifacts59- `.env` file is passed via `env_file` in docker-compose6061## Common Failures6263| Symptom | Likely Cause | Fix |64|---------|-------------|-----|65| `ModuleNotFoundError` | Dependency missing in `pyproject.toml` | `uv add <package>` in the example, rebuild |66| `Connection refused` on port 8000 | App not binding to `0.0.0.0` | Set `--host 0.0.0.0` in uvicorn command |67| Container restarts in loop | Crash on startup (missing env var) | Check `.env` file, compare with `.env.example` |68| `network X not found` | Compose network not created | Run `docker compose down` then `up` again |69| Build fails at `uv sync` | Lock file out of sync | Run `uv lock` locally first, then rebuild |7071## Shell Commands (PowerShell)7273```powershell74# Build and run from example directory75docker compose up --build7677# Rebuild single service78docker compose up --build agent7980# View logs for a service81docker compose logs -f agent8283# Full reset (remove containers, networks, volumes)84docker compose down -v85```8687---88> Source: [ksopyla/agent-patterns-lab](https://github.com/ksopyla/agent-patterns-lab) — distributed by [TomeVault](https://tomevault.io).89<!-- tomevault:4.0:skill_md:2026-05-22 -->
Run npx get-skill add tomevault-io/ksopyla-agent-patterns-lab-docker-debugger in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Docker Debugger It is listed under DevOps & Infra on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
tomevault-io (@tomevault-io) published this skill. Their other Agent Skills are listed on their SkillMD profile.
