Introduction When Docker Compose services use health check-based depends_on, a failing health check prevents dependent services from starting. This is a safety feature but can cause cascading startup failures.

Symptoms - `docker-compose up` shows: "Service X is waiting for Y to become healthy" - Dependent service never starts - Health check container shows unhealthy in `docker-compose ps` - No error message, just indefinite waiting

Common Causes - Health check endpoint not implemented or misconfigured - Health check interval too short for slow-starting services - Database migrations blocking health check response - Health check path returns wrong status code - Service listening on wrong interface (127.0.0.1 vs 0.0.0.0)

Step-by-Step Fix 1. **Check service health status**: ```bash docker-compose ps docker inspect --format='{{.State.Health.Status}}' <container-name> docker inspect --format='{{json .State.Health.Log}}' <container-name> ```

  1. 1.Test the health check command manually:
  2. 2.```bash
  3. 3.docker exec <container-name> curl -f http://localhost:8080/health || echo "Health check failed"
  4. 4.`
  5. 5.Adjust health check configuration:
  6. 6.```yaml
  7. 7.services:
  8. 8.db:
  9. 9.image: postgres:15
  10. 10.healthcheck:
  11. 11.test: ["CMD-SHELL", "pg_isready -U postgres"]
  12. 12.interval: 10s
  13. 13.timeout: 5s
  14. 14.retries: 5
  15. 15.start_period: 30s
  16. 16.`
  17. 17.The start_period gives the service time to initialize before health checks count.
  18. 18.Use restart policy for failed services:
  19. 19.```yaml
  20. 20.services:
  21. 21.api:
  22. 22.depends_on:
  23. 23.db:
  24. 24.condition: service_healthy
  25. 25.restart: on-failure:3
  26. 26.`

Prevention - Always set start_period for health checks on slow-starting services - Use simple, fast health check commands - Implement readiness endpoints that check actual dependencies - Set reasonable retry counts (3-5) and intervals (10-30s) - Use docker-compose logs <service> to debug health check failures