Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Docker Compose rejects depends_on with a condition and says it should be an array

Errordepends_on contains an invalid type, it should be an array

Short answer

The short depends_on form is a list of service names and cannot hold a condition. Conditions need the long form, a map with the service name as the key. Also check you run Compose v2 (docker compose), because the old docker-compose v1 tool is unmaintained and may reject files that v2 accepts.

  • Applies to Docker Compose 2.2x, Docker Engine 28
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print which Compose binary and version runs your file, and let it validate the file. The error message gives the service and key.

    docker compose version
    docker compose config
  2. 2Match what you see, then jump to its fix

    1. 1depends_on has dash items, and a condition line sits under or beside them.condition written under the short list syntaxFix
    2. 2You type docker-compose with a hyphen, and docker compose version either fails or shows a different tool.The file is run by docker-compose v1, not Compose v2Fix

What does the error look like?

  • depends_on contains an invalid type, it should be an array
  • Compose will not start the project after condition: service_healthy was added to depends_on

Cause 1 of 2

condition written under the short list syntax

1Check

In the short syntax, depends_on lists service names only and means the same as service_started. Compose creates dependencies first but does not wait for them to be healthy.

grep -n -A6 "depends_on" compose.yaml

2Fix

Switch to the long syntax: each dependency becomes a key with its own condition. service_healthy needs a healthcheck on that dependency.

services:
  web:
    build: .
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:18
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 10

3Verify

Compose accepts the file and prints it merged.

docker compose config

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 2

The file is run by docker-compose v1, not Compose v2

1Check

docker-compose is Compose v1, written in Python; docker compose is Compose v2, built into the Docker CLI. Docker's migration page says v1 is no longer maintained and users should move to v2.

docker-compose --version
docker compose version

2Fix

Install the Docker Compose plugin and run docker compose instead of docker-compose, with the same file.

docker compose up -d

3Verify

The same file now starts, and the condition is respected.

docker compose ps

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Write depends_on in the long syntax whenever a service needs a condition, a restart or required setting.
  • Remove the old top-level version line; Compose treats it as obsolete and only warns about it.
  • Run docker compose config in CI so a bad file fails before deploy.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.