Fix 'ERROR: The Compose file is invalid because: Unsupported config option for services' in Docker Compose

What happened

You ran docker-compose up and got hit with:

ERROR: The Compose file './docker-compose.yml' is invalid because: Unsupported config option for services

Two things typically cause this. Either your docker-compose.yml uses a schema version that the installed Compose binary doesn't support, or it references config options that were added (or dropped) in a different file format version.

What makes this annoying: the error doesn't say which option failed or why. You have to dig.

Confirm the versions you're working with

Start by pinning down what's actually installed:

# Legacy standalone binary
docker-compose --version
# Docker Compose V2 (plugin)
docker compose version

Then check your compose file's declared version:

head -5 docker-compose.yml

The version field — like "3.8" or "2.4" — tells Docker Compose which schema to use for validation. If the file version sits outside the binary's supported range, you get this error.

Version compatibility quick reference

• Compose file 2.x → requires docker-compose v1.6+
• Compose file 3.0–3.3 → requires docker-compose v1.13+
• Compose file 3.7 → requires docker-compose v1.25+
• Compose file 3.8 → requires docker-compose v1.26+
• No version field (Compose spec) → requires Docker Compose V2 (plugin)

Common causes and fixes

Cause 1: File declares a version too new for the installed binary

Say your docker-compose.yml opens with version: "3.8" but you're running docker-compose 1.24.x. That binary shipped before 3.8 existed — it has no idea what 3.8 features look like.

Fix A — Upgrade docker-compose:

# On Linux (replace with latest version)
sudo curl -L "https://github.com/docker/compose/releases/download/v2.27.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
docker-compose --version

Fix B — Downgrade the version field in your file:

# Change this:
version: "3.8"

# To something your binary supports, e.g.:
version: "3.4"

Only go with Fix B if you're not actually using any 3.8-specific options — things like configs with external templates or deploy.rollback_config.

Cause 2: No version field — Compose Spec format on a V1 binary

Omitting the version field is valid in the modern Compose Spec. But that format is only understood by Compose V2 (the docker compose plugin). The old standalone docker-compose binary doesn't handle it.

# Wrong: using legacy binary
docker-compose up   # fails on Compose Spec files

# Right: use the V2 plugin
docker compose up

Stuck on a system that only has V1? Add an explicit version declaration to your file:

version: "3.8"
services:
  app:
    image: myapp:latest
    ...

Cause 3: Using an option that doesn't exist in the declared version

Some options are version-gated. init: true, for example, was introduced in Compose file format 3.7. Declare version: "3.4" and use init: true in the same file, and you'll hit this error every time.

# Triggers error under version: "3.4"
services:
  app:
    image: myapp
    init: true   # introduced in 3.7

The fix is straightforward — bump the version field to match the option you're using:

version: "3.7"   # now init: true is valid
services:
  app:
    image: myapp
    init: true

Cause 4: Typos or wrong indentation in YAML

Not every "unsupported config option" error is actually a version problem. Malformed YAML gets misreported the same way. A key at the wrong indentation level looks like an unknown option to Docker Compose — because it can't find where to place it in the schema.

# Broken: 'ports' is at wrong indent level
services:
  app:
    image: nginx
  ports:        # wrong! should be under 'app'
    - "80:80"

# Fixed:
services:
  app:
    image: nginx
    ports:      # correct indent under the service
      - "80:80"

Paste your file into the YAML ↔ JSON Converter on ToolCraft to catch these fast. It converts YAML to JSON entirely in the browser — nothing gets uploaded — and structural problems become obvious immediately.

Pinpoint which option is actually failing

"Unsupported config option" tells you something is wrong. It doesn't tell you what. Run with --verbose to get more signal:

docker-compose --verbose config 2>&1 | head -40

Or just validate the file without starting anything:

docker-compose config

This command parses the compose file and prints the resolved config. Structural problems surface here with slightly more context than the original error message gives you.

Verify the fix worked

# 1. Validate the file parses cleanly
docker compose config
# or for V1:
docker-compose config

# 2. Dry run to confirm services resolve
docker compose config --services

# 3. Bring up in detached mode
docker compose up -d

# 4. Confirm containers are running
docker compose ps

Clean output from docker compose config — no errors, just the merged config — means you're done.

What to take away from this

• Pin your Compose file version deliberately. Copying version: "3.8" from a tutorial is fine — just verify your CI environment's Compose binary actually supports it first.
• Switch to Compose V2 (docker compose). Docker officially deprecated the standalone V1 binary in 2023. If your CI or server still calls docker-compose, migrate sooner rather than later. V2 supports the Compose Spec and is actively maintained.
• Lint YAML before committing. A 10-second paste into the ToolCraft YAML converter catches indentation bugs before they reach your pipeline.
• Use docker compose config as your first diagnostic. It validates the file without spinning up a single container — fastest way to rule out a structural problem.