🚨 Docker Error Guide: 'Version is unsupported' — The Obsolete Compose version Key

Overview

Compose rejects your file because of the version it declares at the top:

Version in "./docker-compose.yml" is unsupported. You might be seeing this error because you're using the wrong Compose file version.

The top-level version: key selected a Compose file schema in the v1 era. In Compose v2 that key is obsolete — the schema is unified and versionless — and an out-of-range or malformed value triggers this error (or, on newer releases, a deprecation warning). The reliable fix on modern Compose is to delete the version: line entirely.

Symptoms

• docker compose config or docker compose up fails naming an unsupported version string.
• Newer Compose prints the attribute 'version' is obsolete, it will be ignored as a warning rather than a hard error.
• A file with version: "2" or version: "3" works on one host and fails on another with different Compose releases.
• The value is quoted oddly (version: 3.8 as a float vs version: "3.8" as a string) and parsing behaves inconsistently.
• Copy-pasted legacy tutorials specify version: keys that your Compose no longer accepts.

Common Root Causes

• version: key present on Compose v2. The key is obsolete; a stale or invalid value surfaces as unsupported.
• A version string your Compose does not recognize — e.g. an old 2.0/2.1 micro-version or a typo like 3..8.
• Version/feature mismatch. The file declares a schema version that predates features it uses, or vice versa.
• Mismatched Compose binary. A very old docker-compose v1 is being invoked against a file written for a newer schema.
• YAML type confusion. version: 3.8 parses as a number and rounds/reformats unexpectedly instead of a string.

Diagnostic Workflow

Check which Compose you are actually running — v1 and v2 treat version: very differently:

docker compose version
docker-compose version

Ask Compose to parse and normalize the file; this reports the exact offending value:

docker compose config

The legacy form that triggers the error or warning:

version: "3.8"          # obsolete on Compose v2
services:
  web:
    image: registry.example.com/myapp:1.4.2
    ports:
      - "8080:8080"

The modern, versionless form Compose v2 expects — simply remove the line:

services:
  web:
    image: registry.example.com/myapp:1.4.2
    ports:
      - "8080:8080"

Re-validate and start:

docker compose config
docker compose up -d

Example Root Cause Analysis

A platform team maintained a fleet of servers with mixed Docker versions. Their canonical docker-compose.yml began with version: "2", a holdover from an early deployment. On a host still running the legacy docker-compose v1 binary, upgrading the file to use a newer feature caused v1 to complain the schema version was too low; on a host running Compose v2, the version: "2" key was flagged as unsupported/obsolete.

The team was effectively caught between two eras: one binary demanded a version key, the other rejected it. Their resolution was to standardize on Compose v2 across the fleet (installing docker-compose-plugin everywhere), delete the version: key from the file entirely, and run docker compose config in CI to prove the versionless file parsed cleanly. With v1 fully retired, the version: key had no reason to exist, and the “unsupported” error could not recur.

Prevention Best Practices

• Delete the version: key from all Compose files targeting Compose v2 — it is obsolete and only a liability.
• Standardize on Compose v2 across every host so one file parses identically everywhere; retire the docker-compose v1 binary.
• Run docker compose config in CI to catch schema and version issues before deploy.
• Quote string-like values when you must keep them, so YAML never reinterprets 3.8 as a float.
• Update legacy tutorials before copying them — many still show version: headers that no longer apply. See the Dockerfile & Compose validator.

Quick Command Reference

# Identify your Compose implementation
docker compose version
docker-compose version

# Parse and normalize the file (reports the bad version)
docker compose config

# After removing the version: line
docker compose up -d

Conclusion

Version in "./docker-compose.yml" is unsupported comes from the obsolete top-level version: key. On Compose v2 the schema is versionless, so the safest, most durable fix is to delete the line and let Compose parse the file as-is. Standardize your hosts on Compose v2, remove version: everywhere, and validate with docker compose config so this legacy error stays gone.