Docker Compose — Debugging Strategies

A systematic approach to diagnosing Docker Compose problems.

Step 1: Check Status

docker compose ps -a

Look for containers that are Exited or Restarting.

Step 2: Check Logs

docker compose logs --tail 50 <service>

Look for error messages, stack traces, or crash info.

Step 3: Validate Config

docker compose config -q

If this produces output, you have a YAML/config error.

Step 4: Interactive Shell

docker compose exec <service> sh
# or if it's crashed:
docker compose run --rm <service> sh

Step 5: Override Entrypoint

If a container keeps crashing, override its command:

docker compose run --rm --entrypoint sh api

This starts the container with a shell instead of the normal command, so you can investigate inside.

Step 6: Check Resources

docker stats              # Live CPU/memory
docker system df          # Disk usage
docker system prune       # Clean up

The Debug Toolkit

Check Connectivity

docker compose exec api ping db
docker compose exec api nslookup db
docker compose exec api curl -v http://api:3000/health

Check Environment

docker compose exec api env | sort
docker compose exec api cat /etc/resolv.conf

Check Filesystem

docker compose exec api ls -la /app
docker compose exec api df -h

Check Processes

docker compose top
docker compose exec api ps aux

Rebuild from Scratch

When all else fails:

docker compose down -v --rmi all    # Remove everything
docker compose build --no-cache     # Fresh build
docker compose up -d                # Start clean

Debug Compose File

services:
  debug:
    image: alpine/curl
    command: sleep 3600
    networks:
      - default
    profiles: [debug]

docker compose --profile debug up -d debug
docker compose exec debug sh
# Now debug from inside the network

Common Debugging Commands

Task	Command
Container status	docker compose ps -a
Service logs	docker compose logs --tail 50 <svc>
Shell access	docker compose exec <svc> sh
Network test	docker compose exec <svc> ping <target>
Env vars	docker compose exec <svc> env
Processes	docker compose top
Resource usage	docker stats
Validate YAML	docker compose config -q
Full rebuild	docker compose down -v --rmi all

Summary

Step	Action	Command
1	Check status	ps -a
2	Check logs	logs --tail 50
3	Validate config	config -q
4	Shell in	exec <svc> sh
5	Override entry	run --entrypoint sh
6	Check resources	docker stats

---

Quick Reference

Item	Detail
Status	docker compose ps -a
Logs	docker compose logs –tail 50
Validate	docker compose config -q
Shell	docker compose exec sh
Override	run –rm –entrypoint sh
Clean slate	down -v –rmi all && build –no-cache