dependency cycle detected: a -> b -> a — two services list each other under depends_on, so neither can start first. Remove one direction of the dependency, keeping the one that says which service really has to be up first, and the project starts.

The message spells out the loop: a depends on b, which depends on a. Decide which of the two is the dependency (a database, a queue, an API the other calls) and delete the depends_on entry on that one.

The error

PS> docker compose up -d
dependency cycle detected: a -> b -> a

The command exited with code 1 and created nothing. docker compose config printed the same line and also exited with code 1. The file that produced it: 

name: fix9-cmp-c6
services:
  a:
    image: alpine
    command: ["sleep", "300"]
    depends_on:
      - b
  b:
    image: alpine
    command: ["sleep", "300"]
    depends_on:
      - a

Why it happens

depends_on sets a start order: a service starts after the services it lists. When a waits for b and b waits for a, there is no order that satisfies both, and Compose rejected the file before it created a network or a container. Because config fails too, the cycle can be found without starting anything.

A file can reach this state when two services talk to each other and someone adds a depends_on for each direction of the conversation. The start order can run one way only, so one of the two entries has to go.

The fix

name: fix9-cmp-c6
services:
  a:
    image: alpine
    command: ["sleep", "300"]
    depends_on:
      - b
  b:
    image: alpine
    command: ["sleep", "300"]
PS> docker compose up -d
...
 Container fix9-cmp-c6-b-1 Created
 Container fix9-cmp-c6-a-1 Creating
 Container fix9-cmp-c6-a-1 Created
 Container fix9-cmp-c6-b-1 Starting
 Container fix9-cmp-c6-b-1 Started
 Container fix9-cmp-c6-a-1 Starting
 Container fix9-cmp-c6-a-1 Started

With the depends_on on b removed, Compose created and started b first and a after it, the order the remaining line asks for. Both containers were up in docker compose ps. A later docker compose down -v stopped a before b, the reverse order.

If both services call each other, keep one direction in depends_on; the other service has to cope with its partner not being up yet.

How it was reproduced

Two alpine services, a and b, running sleep 300 and listing each other under depends_on, started with docker compose up -d and checked with docker compose config from Windows PowerShell 5.1 on Docker Engine 29.9.3 and Docker Compose v5.7.0 (Docker Desktop on Windows 11). The project name carries this test's fix9-cmp- prefix and was removed with docker compose down -v.

Frequently asked

What does 'dependency cycle detected' mean in Docker Compose?
Services list each other under depends_on, so no start order works. In this test a depended on b and b on a, and Compose printed a -> b -> a and created nothing.
How do I fix a depends_on cycle in docker-compose.yml?
Remove the depends_on entry on the service that should start first. With only a depending on b, Compose started b and then a.
Can two Docker Compose services depend on each other?
Not through depends_on. Both up and config rejected the file with the two entries. Keeping one direction made the file valid and both services started.

More decoded errors in the Fixes category. When depends_on names a service that is not in the file, see Docker Compose: service depends on undefined service.