Docker Compose "cyclic dependency detected" in CI

By Daniel Zoghalchali·Latchkey

depends_on defines a startup order, and compose topologically sorts services from it. When the dependencies form a cycle - A depends on B and B depends on A - there is no valid order and compose refuses to start with "cyclic dependency detected".

What this error means

A docker compose up fails immediately with cyclic dependency detected naming the services in the loop, before any container starts.

cyclic dependency detected: service "web" depends on "api" depends on "web"

Common causes

Two services depend on each other

A and B each list the other in depends_on, creating a loop with no start order.

A longer dependency cycle

A chain A -> B -> C -> A forms a cycle through several services.

How to fix it

Break the cycle in depends_on

1. Remove the dependency that creates the loop; keep only the true startup ordering.

services:
  web:
    depends_on:
      - api
  api: {}   # api must NOT depend on web

Use runtime readiness instead of mutual depends_on

1. If services genuinely need each other at runtime, let one retry the connection at startup rather than encoding a cyclic dependency.

# in the app: retry the peer connection with backoff
# instead of api depends_on web AND web depends_on api

How to prevent it

• Keep depends_on a strict DAG; never let two services depend on each other.
• Handle mutual runtime needs with connection retries, not startup ordering.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation