Skip to main content

Dependency Cycle

Symptoms​

  • server exits before runtime with a cycle error
  • error includes dependency cycle detected among services
  • no services are launched

Why it happens​

FlowLayer computes startup waves from dependsOn.

A cycle means there is no valid first wave. Common examples:

  • api -> worker -> api
  • db-migrate -> api -> db-migrate
  • indirect loop across 3 or more services

Resolution​

  1. List dependsOn edges on paper or in a quick diagram.
  2. Find one edge that is not a hard startup requirement.
  3. Remove that edge.
  4. Keep only dependencies required to boot safely.
  5. Run server again.

Example loop:

{
  "services": {
    "api": {"cmd": ["go", "run", "./cmd/api"], "dependsOn": ["worker"]},
    "worker": {"cmd": ["go", "run", "./cmd/worker"], "dependsOn": ["api"]}
  }
}

Fix by removing one edge and handling runtime coordination inside the service logic instead of startup topology.

Prevention​

  • model boot dependencies, not call graph dependencies
  • avoid mutual startup dependencies
  • use readiness checks on real providers (db, broker) rather than cross-coupling peers

See Waves and Services.