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

- **ID:** `docker/compose-service-dependency-cycle`
- **Domain:** docker
- **Category:** config_error
- **Verification:** ai_generated
- **Fix Rate:** 95%

## Root Cause

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

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| Docker Compose v2.0.0 | active | — | — |
| Docker Compose v2.20.0 | active | — | — |
| Docker Compose v2.24.0 | active | — | — |

## Workarounds

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.** (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.
   ```
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 } }'.** (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 } }'.
   ```

## Dead Ends

- **** — Removing all depends_on directives breaks the intended startup order and may cause runtime failures if services depend on each other for readiness. (70% fail)
- **** — Adding a third service that depends on both only masks the cycle temporarily; the underlying dependency graph remains invalid. (80% fail)