docker config_error ai_generated true

ERROR: Circular dependency detected: service1 depends on service2 which depends on service1

ID: docker/compose-service-dependency-cycle

Also available as: JSON · Markdown · 中文
95%Fix Rate
90%Confidence
1Evidence
2023-11-01First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
Docker Compose v2.0.0 active — — —
Docker Compose v2.20.0 active — — —
Docker Compose v2.24.0 active — — —

Root Cause

In a docker-compose.yml file, services have a circular dependency chain via the 'depends_on' directive, which Docker Compose cannot resolve.

generic

中文

在 docker-compose.yml 文件中，服务通过 'depends_on' 指令形成了循环依赖链，Docker Compose 无法解析。

Official Documentation

https://docs.docker.com/compose/compose-file/05-services/#depends_on

Workarounds

  1. 95% success Redesign the service architecture to remove the circular dependency. For example, if service A needs service B and vice versa, consider merging them into a single service or using a message queue. Update docker-compose.yml to remove the cycle. 
    Redesign the service architecture to remove the circular dependency. For example, if service A needs service B and vice versa, consider merging them into a single service or using a message queue. Update docker-compose.yml to remove the cycle.
  2. 85% success Use 'depends_on' with 'condition: service_healthy' and implement health checks instead of direct dependencies. This allows services to start in any order but wait for readiness. Example: 'depends_on: { db: { condition: service_healthy } }'. 
    Use 'depends_on' with 'condition: service_healthy' and implement health checks instead of direct dependencies. This allows services to start in any order but wait for readiness. Example: 'depends_on: { db: { condition: service_healthy } }'.

中文步骤

  1. Redesign the service architecture to remove the circular dependency. For example, if service A needs service B and vice versa, consider merging them into a single service or using a message queue. Update docker-compose.yml to remove the cycle.
  2. Use 'depends_on' with 'condition: service_healthy' and implement health checks instead of direct dependencies. This allows services to start in any order but wait for readiness. Example: 'depends_on: { db: { condition: service_healthy } }'.

Dead Ends

Common approaches that don't work:

  1. 70% fail

    Removing all depends_on directives breaks the intended startup order and may cause runtime failures if services depend on each other for readiness.

  2. 80% fail

    Adding a third service that depends on both only masks the cycle temporarily; the underlying dependency graph remains invalid.