Skip to content
Tutorials Center
My learning

Topics

Lesson 111 of 111 ยท Practice

Practice: Debugging a Broken Compose Stack

Hands-on exercise: fix a Compose stack with six planted bugs (undefined volume, wrong env name, localhost, port mapping, startup race, health check) step by step.

Reading about errors is easy. Fixing a stack that does not work, with no hint about where to look, is the real skill. In this exercise you get a Compose file with six planted bugs. Each one produces a different symptom, and each one is common in real projects. You will use a repeatable debugging routine instead of guessing.

Try each exercise yourself first, on your own machine. Only then read the diagnosis. The code blocks are read-only: this page cannot run Docker, so the messages are described as "something like" what you will see, because exact wording changes between Docker, Compose and PostgreSQL versions.

The stack

An API container that talks to PostgreSQL. Create a folder with these two files. The API is a tiny Node.js server that listens on port 3000, answers GET /health and queries the database on GET /:

DOCKERFILE
FROM node:24-alpine
WORKDIR /app
COPY package.json server.js ./
RUN npm install --omit=dev
USER node
EXPOSE 3000
CMD ["node", "server.js"]

Save this as api/Dockerfile, with any small server.js that reads process.env.DATABASE_URL. Now the broken compose.yaml:

YAML
version: "3.9"

services:
  api:
    build: ./api
    ports:
      - "3000:8080"
    environment:
      DATABASE_URL: postgres://app:secret@localhost:5432/app
    depends_on:
      - db
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 5s
      retries: 3

  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: app
      POSTGRES_PASS: secret
      POSTGRES_DB: app
    volumes:
      - dbdata:/var/lib/postgresql/data

Do not fix anything by reading alone. Run it and let Docker tell you.

The debugging routine

Use the same loop for every problem, from the cheapest question to the most expensive one:

flowchart TD
  A["docker compose config<br/>(is the file valid?)"] --> B["docker compose up -d"]
  B --> C["docker compose ps -a<br/>(who is running, exited, unhealthy?)"]
  C --> D["docker compose logs SERVICE<br/>(what did it say?)"]
  D --> E["docker compose exec SERVICE ...<br/>(look from the inside)"]
  E --> F["Change ONE thing, repeat"]

Validate first, then look at state, then logs, then go inside. Change one thing per round, or you will not know which change worked.

The commands are explained in Compose Commands, Logs and Exec and Debugging Containers. The Common Docker Errors lesson lists many messages you will meet here.

Exercise 1: the file does not even load

Run docker compose config. This command parses and validates the file without starting anything.

What you should notice. Two things. A warning that the top-level version attribute is obsolete and ignored, and an error saying that service db refers to an undefined volume dbdata.

Try to fix these two yourself before reading on. Hint: where are named volumes declared?

Diagnosis. Modern Compose follows the Compose Specification and does not use version, so the line is dead weight. The error is real: using a named volume in a service is not enough, you also declare it at the top level (see Compose Networks and Volumes).

Fix. Delete the version line and add at the bottom:

YAML
volumes:
  dbdata:

Run docker compose config again until it prints the merged file without errors.

Exercise 2: the database exits immediately

Run docker compose up -d, then docker compose ps -a.

Symptom. The db service shows as exited. Read its logs with docker compose logs db.

What you should notice. The PostgreSQL image refuses to start and says something like: the database is uninitialized and the superuser password is not specified. It also explains which variables it understands.

Diagnosis. The official image reads POSTGRES_PASSWORD, not POSTGRES_PASS. An unknown variable is silently ignored by the container: Compose cannot know which names the image expects. This is why the logs, not the file, tell you the truth.

Fix. Rename the variable. Because the first start failed before the data directory was initialized, recreate cleanly:

Terminal
docker compose down --volumes
docker compose up -d

--volumes deletes the named volumes of the project, including database data. That is exactly what you want in a practice stack and exactly what you do not want in production. Read Backup and Restore before you use it on real data.

Exercise 3: the API cannot reach the database

Now db stays up, but docker compose logs api shows connection errors, something like "connection refused" to localhost:5432 or 127.0.0.1:5432, and the container may restart or exit.

Diagnosis. Inside a container, localhost means that container. The API container has nothing listening on port 5432. The database lives in another container, reachable by its service name on the Compose network. You can prove it from the inside:

Terminal
docker compose exec api sh -c 'nc -zv db 5432'

(If nc is missing in your image, getent hosts db also proves that the name db resolves.) The mechanics are explained in Container Communication and Networking Troubleshooting.

Fix.

YAML
    environment:
      DATABASE_URL: postgres://app:secret@db:5432/app

Also notice that the database port needs no ports: entry. Services on the same Compose network talk to each other directly, and ports: is only for traffic from your host.

Exercise 4: published, but nobody answers

The API now starts, but curl http://localhost:3000/ from your machine fails: connection reset or an empty reply.

Diagnosis. Compare the port mapping with the program. The mapping "3000:8080" means host 3000 to container 8080. The program listens on 3000, so traffic arrives at a port where nothing listens. Check with docker compose port api 3000 and docker compose logs api, and read Port Publishing for the rule: the right-hand number is always the one the application uses.

Fix.

YAML
    ports:
      - "3000:3000"

Exercise 5: the race at startup

Run docker compose down and docker compose up -d several times. Sometimes the API logs a connection error in the first seconds and then works, or crashes once and is restarted by hand.

Diagnosis. depends_on: [db] only waits until the database container has started. PostgreSQL needs a few more seconds to accept connections. The fix is to give the database a health check and make the API wait for service_healthy (see Compose Dependencies and Health and Health Checks).

Fix.

YAML
  db:
    image: postgres:17-alpine
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d app"]
      interval: 3s
      timeout: 3s
      retries: 10
  api:
    depends_on:
      db:
        condition: service_healthy

Exercise 6: the API is "unhealthy"

Finally docker compose ps shows the API as running but unhealthy. Look at the reason:

Terminal
docker inspect --format '{{json .State.Health.Log}}' $(docker compose ps -q api)

What you should notice. The last health check output says that curl could not be found.

Diagnosis. The health check command runs inside the image, and node:24-alpine does not ship curl. The check fails every time, no matter how healthy the app is. Use a tool the image has, such as the Node.js runtime itself:

YAML
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/health').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"]
      interval: 5s
      timeout: 3s
      retries: 3
      start_period: 5s

The repaired file

YAML
services:
  api:
    build: ./api
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://app:secret@db:5432/app
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/health').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"]
      interval: 5s
      timeout: 3s
      retries: 3
      start_period: 5s

  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: app
    volumes:
      - dbdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d app"]
      interval: 3s
      timeout: 3s
      retries: 10

volumes:
  dbdata:

After docker compose up -d --wait, both services should show as healthy, and curl http://localhost:3000/health should answer. The password here is a practice value; for real projects use Compose Environment Config and Secrets Management.

Extra challenges

  1. Add a redis:7-alpine service, give it a health check with redis-cli ping, and make the API wait for it too.
  2. Add a second file compose.override.yaml that bind-mounts ./api for development (see Multiple Compose Files).
  3. Break something new on purpose (rename the service, remove a volume) and predict the symptom before you run it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does docker compose config do?

    It is the cheapest first check: syntax errors, undefined volumes and bad interpolation show up before any container is created.
  2. 2. Why does DATABASE_URL with localhost fail inside the api container?

    Each container has its own network namespace. Other services on the same Compose network are reached by service name, such as db.
  3. 3. What does depends_on with only a service name guarantee?

    Plain depends_on orders container start. For readiness, add a health check to the dependency and use condition: service_healthy.
  4. 4. A service is running but unhealthy, and the health log says curl is not found. What is the fix?

    The health check runs inside the container, so it can only use programs that image contains. More retries cannot make a missing binary appear.

Summary

  • Debug in a fixed order: config, ps -a, logs, exec, and change one thing at a time.
  • Named volumes must be declared at the top level; the obsolete version key can be deleted.
  • Containers ignore unknown environment variables silently, so read the image's documentation and the logs.
  • Use service names, not localhost, between containers; the right side of host:container is the app's real port.
  • depends_on alone is a start order. Use health checks with condition: service_healthy for readiness.
  • A health check can only use tools that exist inside the image.

This is the last lesson of the Docker tutorial. Go back to the Docker cheat sheet to review the commands, or try the interview questions.