github/spec-kit · error · BundlerError

Unsupported catalog config schema version '{str(schema_versi

Error message

Unsupported catalog config schema version '{str(schema_version).strip()}' at {path}; this Spec Kit understands version {CONFIG_SCHEMA_VERSION}. The file may have been written by a newer version or is corrupt.

What it means

Raised when `schema_version` in `bundle-catalogs.yml` exists but its major component differs from `CONFIG_SCHEMA_VERSION` known by the installed spec-kit. Major-version mismatch means the file's shape is not understood by this version, so parsing aborts rather than mis-reading fields.

Source

Thrown at src/specify_cli/bundler/commands_impl/catalog_config.py:58

    if not path.exists():
        return []
    # ``load_yaml`` returns ``{}`` only for an empty document and the raw parse
    # otherwise, so a non-mapping top level — a falsy ``[]``/``false``/``0``/``''``
    # or an explicit null (``load_yaml`` -> ``None``) — is caught by the isinstance
    # guard below and raised like a truthy one, staying consistent with the other
    # reader of this file (models/catalog._merge_config).
    data = load_yaml(path)
    if not isinstance(data, dict):
        raise BundlerError(
            f"Malformed catalog config at {path}: expected a mapping at the top "
            f"level, got {type(data).__name__}."
        )
    schema_version = data.get("schema_version")
    if schema_version is not None and (
        str(schema_version).strip().split(".")[0]
        != CONFIG_SCHEMA_VERSION.split(".")[0]
    ):
        raise BundlerError(
            f"Unsupported catalog config schema version "
            f"'{str(schema_version).strip()}' at {path}; this Spec Kit "
            f"understands version {CONFIG_SCHEMA_VERSION}. The file may have been "
            "written by a newer version or is corrupt."
        )
    catalogs = data.get("catalogs")
    if catalogs is None:
        return []
    if not isinstance(catalogs, list):
        raise BundlerError(
            f"Malformed catalog config at {path}: 'catalogs' must be a list, "
            f"got {type(catalogs).__name__}."
        )
    for entry in catalogs:
        if not isinstance(entry, dict):
            raise BundlerError(
                f"Malformed catalog config at {path}: each catalog entry must be "
                f"a mapping, got {type(entry).__name__}."

View on GitHub (pinned to bf88c9f9a8)

Solutions

  1. Align the file's `schema_version` major with the version this CLI understands (shown in the message)
  2. Upgrade spec-kit to the release that wrote the file
  3. Or delete the project-scoped file to fall back to built-in defaults and re-add sources

Example fix

# before
schema_version: "2.0"

# after
schema_version: "1.0"
Defensive patterns

Strategy: validation

Validate before calling

from specify_cli.bundler.models.catalog import CONFIG_SCHEMA_VERSION

major = str(data.get("schema_version", CONFIG_SCHEMA_VERSION)).strip().split(".")[0]
if major != CONFIG_SCHEMA_VERSION.split(".")[0]:
    raise SystemExit(f"config schema {major}.x not understood; CLI knows {CONFIG_SCHEMA_VERSION}")

Type guard

def schema_major_matches(data: dict) -> bool:
    v = data.get("schema_version")
    return v is None or str(v).strip().split(".")[0] == CONFIG_SCHEMA_VERSION.split(".")[0]

Try / catch

try:
    read_catalog_config(project_root)
except BundlerError as exc:
    if "Unsupported catalog config schema version" in str(exc):
        # upgrade spec-kit or regenerate the project-scoped file
        raise
    raise

Prevention

When it happens

Trigger: `schema_version: 2.0` in the file while this CLI understands `1.x`; also triggers for unquoted numeric versions only when the integer part differs (comparison is on `split(".")[0]` of the stringified value).

Common situations: Opening a project created by a newer spec-kit release with an older CLI; hand-writing a version string like `v1` or `1`; downgrading the tool.

Related errors

AI-assisted analysis of github/spec-kit@bf88c9f9a8 (2026-08-14). Data as JSON: /api/errors/4b4798effe579711. Report an issue: GitHub.