This error occurs when using the condition syntax with depends_on in Docker Compose. It typically happens because Compose version 3 removed support for conditions, but modern Docker Compose (v2+) has restored this feature under the Compose Specification.
The "depends_on condition is invalid" error appears when Docker Compose cannot parse your depends_on configuration with a condition attribute. This usually happens because you're using an older version of Docker Compose CLI or a Compose file format that doesn't support the extended depends_on syntax. When Docker Compose v3 was released, it intentionally removed the `condition` form of `depends_on` to target Docker Swarm deployments. However, starting with Docker Compose v1.27.0, the 2.x and 3.x specifications were merged under the Compose Specification, and the condition syntax was restored for standalone Docker Compose usage. The confusion arises because the `version` field in your docker-compose.yml determines which syntax is valid. If you specify `version: "3"` or similar, Docker Compose may reject the condition syntax depending on your CLI version.
The simplest fix is to remove the version field entirely. Modern Docker Compose (v2+) uses the Compose Specification which supports conditions by default:
# Remove this line or update to a higher version
# version: "3" # <-- Delete this
services:
web:
build: .
depends_on:
db:
condition: service_healthy
db:
image: postgres:15
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 10s
timeout: 5s
retries: 5When the version field is omitted, Docker Compose uses the Compose Specification schema which fully supports the condition syntax.
Make sure you're using the modern Docker Compose CLI. The newer version is a Docker plugin and uses a space instead of a hyphen:
# Check your version
docker compose version # Modern v2 (plugin)
docker-compose version # Legacy v1 (standalone)
# Use the modern command
docker compose up # ✅ Use this
docker-compose up # ❌ Avoid if possibleIf you only have docker-compose (with hyphen), install the Docker Compose plugin:
# On Ubuntu/Debian
sudo apt-get update
sudo apt-get install docker-compose-plugin
# Or via Docker Desktop (includes it by default)If you're using condition: service_healthy, the dependency service must define a healthcheck. Without it, Docker Compose cannot determine when the service is "healthy":
services:
app:
build: .
depends_on:
db:
condition: service_healthy
redis:
condition: service_healthy
db:
image: postgres:15
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 10s
timeout: 5s
retries: 5
start_period: 30s
redis:
image: redis:7
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 10s
timeout: 5s
retries: 5Common healthcheck commands:
- PostgreSQL: pg_isready -U <user>
- MySQL: mysqladmin ping -h localhost
- Redis: redis-cli ping
- Generic HTTP: curl -f http://localhost:8080/health
If you cannot upgrade to Docker Compose v2 and must use the legacy CLI, use version 2.4 which supports the condition syntax:
version: "2.4"
services:
app:
build: .
depends_on:
db:
condition: service_healthy
db:
image: postgres:15
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 10s
timeout: 5s
retries: 5Note: Version 2.x files don't support Swarm mode features like deploy, but they provide full depends_on condition support.
Ensure your depends_on uses the correct long-form syntax with proper indentation:
# ❌ WRONG - Array syntax (no conditions)
depends_on:
- db
- redis
# ❌ WRONG - Incorrect nesting
depends_on:
db:
condition: service_healthy
# ✅ CORRECT - Long-form syntax
depends_on:
db:
condition: service_healthy
redis:
condition: service_startedAvailable conditions:
- service_started - Wait for container to start (default)
- service_healthy - Wait for healthcheck to pass
- service_completed_successfully - Wait for container to exit with code 0
Understanding Compose versioning history: Docker Compose v3 was designed for Swarm compatibility and intentionally removed the condition syntax because Swarm handles orchestration differently. The Compose Specification (post v1.27.0) reunified the syntax, making conditions available again for standalone Docker Compose usage.
Using `restart: true` with depends_on: In the Compose Specification, you can also use restart: true to automatically restart a service when its dependency is restarted:
depends_on:
db:
condition: service_healthy
restart: trueThe `required` option: Set required: false to make a dependency optional (service starts even if dependency fails):
depends_on:
cache:
condition: service_healthy
required: falseWait scripts as an alternative: If you're stuck on old infrastructure, consider using wait scripts like wait-for-it.sh, dockerize, or wait-for:
services:
app:
command: ["./wait-for-it.sh", "db:5432", "--", "npm", "start"]
depends_on:
- dbCI/CD considerations: In CI environments, ensure the Docker Compose version matches your local development. Pin specific versions in your CI configuration to avoid version-related failures.
dockerfile parse error line 5: unknown instruction: RRUN
How to fix 'unknown instruction' Dockerfile parse error in Docker
Error response from daemon: manifest for nginx:nonexistent not found: manifest unknown: manifest unknown
How to fix 'manifest for image:tag not found' in Docker
Error response from daemon: invalid reference format: repository name must be lowercase
How to fix 'repository name must be lowercase' in Docker
Error response from daemon: No such image
How to fix 'No such image' in Docker
Error response from daemon: Container is not running
How to fix 'Container is not running' when using docker exec