Docker Compose Depends On Not Waiting Fix

In this tutorial, you'll learn about Docker Compose Depends On Not Waiting Fix. We cover key concepts, practical examples, and best practices.

depends_on in Docker Compose controls startup order, but it only waits for the container to start, not for the service inside it to be ready. This means your web app starts before the database is accepting connections, causing connection errors.

The Problem

docker-compose up

The web service starts but immediately fails:

web_1  | django.db.utils.OperationalError: could not connect to server: Connection refused
web_1  | Is the server running on host "db" and accepting TCP/IP connections on port 5432?

Wrong Approach

# WRONG — depends_on only waits for container start, not readiness
services:
  web:
    image: my-app:latest
    depends_on:
      - db
  db:
    image: postgres:15

Right Approach

# RIGHT — use healthcheck and condition for proper waiting
services:
  web:
    image: my-app:latest
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:15
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

Step-by-Step Fix

Step 1: Add a healthcheck to the dependency service

services:
  db:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: secret
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

Step 2: Set depends_on with condition

services:
  web:
    image: my-app:latest
    depends_on:
      db:
        condition: service_healthy

Step 3: Add restart logic as a fallback

services:
  web:
    image: my-app:latest
    depends_on:
      db:
        condition: service_healthy
    restart: on-failure

Step 4: Test the waiting behavior

docker-compose up -d db
docker-compose logs db

Expected:

db | PostgreSQL init process complete; ready for accept connections
db | database system is ready to accept connections

Then start web:

docker-compose up -d web

Step 5: Verify the startup order

docker-compose logs web | head

Expected output shows successful database connection on first attempt.

Prevention Tips

• Always use condition: service_healthy for critical dependencies
• Add healthchecks to all database and cache services
• Implement application-level retry logic as a second layer of defense
• Use restart: on-failure so containers retry after the dependency is ready
• Test startup order with docker-compose up after every compose file change

Common Mistakes with compose depends

1. Using head and tail instead of pattern matching, causing runtime errors on empty lists
2. Forgetting that lazy evaluation defers computation until the value is forced, causing space leaks with unevaluated thunks
3. Using return to exit a function early instead of wrapping a pure value in the monad

These mistakes appear frequently in real-world DOCKER code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ