🐳 Docker Error Guide: 'depends_on condition is not supported' Compose Failure

Exact Error Message

ERROR: The Compose file './docker-compose.yml' is invalid because:
services.web.depends_on contains an invalid type, it should be an array
services.web.depends_on.db.condition is not supported

With the newer Compose v2 CLI you may instead see:

validating docker-compose.yml: services.web.depends_on.db condition "service_healthy"
is not allowed by this Compose specification version

Both are the same problem: the long depends_on syntax with a condition key is being parsed by a tool or file version that does not understand it.

What It Means

depends_on has two forms. The short form is a plain list of service names and only controls start order:

depends_on:
  - db

The long form lets you gate startup on a health or completion condition:

depends_on:
  db:
    condition: service_healthy

The long form (with condition: service_healthy, service_started, or service_completed_successfully) was introduced in Compose file format 3.4 for the legacy docker-compose v1 tool, and later removed from the 3.x schema before being restored under the unified Compose Specification used by docker compose v2. If your version: line, your Compose binary, or a validation tool predates support for that condition, you get this error. It is a schema-compatibility failure, not a runtime bug.

Common Causes

• You are running the old Python docker-compose (v1) binary, which only supports conditions on file format 2.1/2.x and 3.4+.
• A version: "3" or version: "3.0" header in the file, which does not allow the condition key.
• A CI image or teammate’s machine still ships docker-compose v1 while you use docker compose v2 locally.
• A third-party linter or deployment platform validates against an older Compose schema.
• depends_on written as a mapping while the tool expects the short-form array.

Diagnostic Commands

Check which Compose you are actually running. The v1 binary and v2 plugin report differently:

docker-compose version
docker compose version

Validate and render the effective config so you can see how the tool interprets depends_on:

docker compose config

Confirm the file format header the file declares:

grep -n "version:" docker-compose.yml

If a service defines a healthcheck (required for service_healthy), inspect it:

docker compose config | grep -A6 healthcheck

Step-by-Step Resolution

1. Prefer the modern docker compose v2 plugin over the deprecated docker-compose v1 script. v2 fully supports long-form conditions and ignores the version: field entirely:

docker compose up -d

2. If you must stay on v1, set a file format that supports conditions. Use 2.1+ or 3.4+:

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

3. Add a real healthcheck to any dependency you gate with condition: service_healthy. Without one, service_healthy can never be satisfied and the dependent service will not start.

4. If you do not actually need health gating, drop back to the short-form array, which every version accepts:

depends_on:
  - db

5. Align your CI and teammates on the same Compose. Uninstall the stale v1 binary or install the Compose v2 plugin so validation is consistent everywhere:

docker compose version

6. Re-validate, then bring the stack up and confirm the dependent service waits correctly:

docker compose config -q && docker compose up -d

[+] Running 2/2
 ✔ Container app-db-1   Healthy
 ✔ Container app-web-1  Started

Prevention

• Standardize on docker compose (v2) across laptops, CI, and servers so schema support never diverges.
• Remember that depends_on conditions only wait for start or health, not for an application to be fully ready; still design services to retry their own connections.
• Always pair condition: service_healthy with a healthcheck on the target service.
• Drop the version: top-level key for v2 projects; it is obsolete and only invites schema confusion.
• Lint Compose files in CI with docker compose config -q using the same binary you deploy with. For repeatable multi-service scaffolds, the DevOps AI prompt library can generate healthcheck-gated Compose files.

Related Errors

• services.web.depends_on contains an invalid type, it should be an array — the mapping form rejected by a short-form-only parser.
• dependency failed to start: container ... is unhealthy — the healthcheck exists but never turns healthy.
• service ... has neither an image nor a build context specified — an unrelated service-definition error.
• The Compose file is invalid because: Unsupported config option — a different schema-version mismatch.

Frequently Asked Questions

Why does docker compose v2 work when docker-compose v1 fails on the same file? v2 uses the unified Compose Specification and ignores the version: key, so long-form depends_on conditions are always supported. v1 validates against the declared file format, which must be 2.1+ or 3.4+.

What healthcheck do I need for condition: service_healthy? The dependency must define a healthcheck that eventually reports healthy. Without one, the state stays starting and the dependent service never launches.

Should I still put a version: line in my Compose file? No. For Compose v2 it is obsolete and can cause older validators to reject valid condition syntax. Remove it.

Does depends_on guarantee my database is ready to accept queries? No. service_healthy only reflects the healthcheck result; service_started only reflects process start. Applications should still retry connections on startup. For more patterns, see the Docker guides.