docker/cli · error

unsupported Compose file version

Error message

unsupported Compose file version: %s

What it means

Raised by schema.Validate when the embedded schema file for the requested Compose version cannot be read (schema.go:80-82). The version is normalized (empty or "3" becomes "3.13"), then the code looks for `data/config_schema_v<version>.json`. A read failure means no embedded schema matches that version, so the Compose file declares a version the bundled CLI does not know.

Solutions

1. Check the `version:` field in the Compose file and set it to a supported value (e.g. "3.13" or remove the field entirely so the default 3.13 is used).
2. Upgrade the Docker CLI to a version that bundles the schema for the declared Compose version.
3. Run `docker compose config` to confirm the version is accepted before deploying.

Example fix

// before
version: "2.0"
// after (omit to use default latest, or pin a supported value)
# version: "3.13"

// Validate the version against the known supported set before calling Validate.
var supported = map[string]bool{"2.1":true,"2.2":true,"2.3":true,"2.4":true,"3":true,"3.1":true,"3.13":true}
if !supported[version] {
    return fmt.Errorf("unsupported Compose version %q; use 3.13 or omit version", version)
}

func isSupportedVersion(v string) bool {
    switch v {
    case "", "3", "2.1","2.2","2.3","2.4","3.1","3.13":
        return true
    }
    return false
}

if err := schema.Validate(config, version); err != nil {
    return fmt.Errorf("schema validation: %w", err)
}

When it happens

Trigger: Calling schema.Validate(config, version) with a version string that does not correspond to any embedded `config_schema_v*.json` file (after normalization). E.g. version "2.0" when only "2.1"–"3.13" schemas are bundled, or a malformed version like "3x".

Common situations: A Compose file declares an unsupported or misspelled `version:` (e.g. `version: "4"`, `version: "2.0.0"`, or a removed/old version). Upgrading the Docker CLI can drop schemas for deprecated versions; downgrading a file to a version newer than the CLI supports produces it too.

Related errors

• version mismatched between two composefiles
• specify a Compose file (with --compose-file)
• cluster options are incompatible with type image
• invalid bind source, source cannot be empty
• volume options are incompatible with type bind

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/ad359aab4ed99d2c. Report an issue: GitHub.

Appendix: source

Thrown at cli/compose/schema/schema.go:82

func normalizeVersion(version string) string {
	switch version {
	case "", "3":
		return defaultVersion
	default:
		return version
	}
}

//go:embed data/config_schema_v*.json
var schemas embed.FS

// Validate uses the jsonschema to validate the configuration
func Validate(config map[string]any, version string) error {
	version = normalizeVersion(version)
	schemaData, err := schemas.ReadFile("data/config_schema_v" + version + ".json")
	if err != nil {
		return fmt.Errorf("unsupported Compose file version: %s", version)
	}

	schemaLoader := gojsonschema.NewStringLoader(string(schemaData))
	dataLoader := gojsonschema.NewGoLoader(config)

	result, err := gojsonschema.Validate(schemaLoader, dataLoader)
	if err != nil {
		return err
	}

	if !result.Valid() {
		return toError(result)
	}

	return nil
}

func toError(result *gojsonschema.Result) error {

View on GitHub (pinned to 4f84911bfe)