Docker Compose Debugging Checklist

Services, logs, ports, volumes, env files and healthchecks. Last updated August 31, 2026.

Docker Compose is commonly used to define and run multi-container application stacks from one YAML file. Docker's own documentation describes Compose as a way to manage services, networks and volumes across environments. This Formalint checklist is for the debugging moment: the stack is not healthy, one container keeps restarting, a database is not reachable, or a developer needs to prove exactly what Compose started.

Start with the project state

docker compose version
docker compose config
docker compose ps
docker compose top
docker compose ls

Read logs without flooding the terminal

Use bounded log windows first. Full log streams are useful only after you know which service is failing.

docker compose logs --tail=120
docker compose logs --tail=120 api
docker compose logs --since=30m db
docker compose events --json

Inspect one service

docker compose exec api sh
docker compose exec api env | sort
docker compose exec api getent hosts db
docker compose exec api nc -vz db 5432
docker inspect $(docker compose ps -q api)

Ports, networks and volumes

Question	Command	What it proves
Is the host port bound?	`docker compose ps`	The service is published to the expected host port.
Can containers resolve each other?	`getent hosts service`	Compose DNS sees the target service name.
Is data persisted?	`docker volume ls`	The database or upload path is using a volume.
Did config render correctly?	`docker compose config`	Overrides, env files and YAML merges produced the expected final config.
Is the image stale?	`docker compose build --no-cache service`	The failure is not from an old layer or cached dependency install.

Safe rebuild order

For developer machines, rebuild one service before tearing down volumes. Removing volumes can delete local databases, queues or uploaded test files.

docker compose pull
docker compose build api
docker compose up -d api
docker compose ps
docker compose logs --tail=80 api

Healthcheck and dependency debugging

docker inspect --format='{{json .State.Health}}' $(docker compose ps -q api)
docker compose restart api
docker compose exec api curl -I http://localhost:3000/health
docker compose exec api printenv | grep -E 'DATABASE|REDIS|QUEUE|PORT|HOST' | sort

Compose incident notes

Save the rendered config, service list, relevant logs and container IDs when handing the issue to another developer or DBA.

date -Is
hostname
git rev-parse --short HEAD
docker compose version
docker compose ps
docker compose logs --tail=120 api db

Do not start with down -v. First prove config, logs, DNS, ports and volumes. Then rebuild or reset only the piece that explains the failure.