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 {config_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 a bundle-catalogs.yml declares a schema_version whose major component differs from CONFIG_SCHEMA_VERSION understood by the running Spec Kit. This mirrors the sibling reader (commands_impl/catalog_config._read) so both readers of the file agree: a newer-schema file is rejected on the resolution path instead of being silently parsed under v1 assumptions.

Source

Thrown at src/specify_cli/bundler/models/catalog.py:293

    # aligned the inner non-list ``catalogs`` value between the two readers.
    data = load_yaml(config_path)
    if not isinstance(data, dict):
        raise BundlerError(
            f"Malformed catalog config at {config_path}: expected a mapping at "
            f"the top level, got {type(data).__name__}."
        )
    # Reject an unsupported major schema version, matching the sibling reader
    # commands_impl/catalog_config._read. Without this, a file written by a
    # newer/incompatible Spec Kit was silently parsed under v1 assumptions on
    # the resolution path (bundle search/install), while the other reader
    # rejected it — the two readers disagreed. An absent schema_version stays
    # valid (backward compatible with configs that omit it).
    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 {config_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):
        # Treat only an absent/``None`` ``catalogs`` as "nothing to merge"; any
        # other non-list value (``catalogs: 5``, ``false``, ``0``, ``''``,
        # ``{}``) is a malformed config and must raise, not be silently skipped
        # by a falsy check. Otherwise a truthy scalar would raise a raw
        # ``TypeError: 'int' object is not iterable`` from the loop below, while
        # falsy non-lists would be swallowed. Report the same actionable
        # BundlerError the sibling reader of this file raises
        # (commands_impl/catalog_config.py) so both readers of
        # bundle-catalogs.yml agree. An empty list stays valid (loop is a no-op).

View on GitHub (pinned to bf88c9f9a8)

Solutions

1. Upgrade Spec Kit ('pip install -U specify-cli' or your package manager) so the CLI understands the file's schema major.
2. Edit the file's schema_version down to the supported major and adjust any newer-format keys to the v1 layout.
3. If the file's extra content is not needed, delete it and let the tooling regenerate/ignore it.
4. Check the sibling reader's supported version (CONFIG_SCHEMA_VERSION) to confirm what major is expected.

Example fix

# before (bundle-catalogs.yml)
schema_version: 2
catalogs: [...]

# after
schema_version: 1
catalogs: [...]

import yaml
from pathlib import Path

SUPPORTED_MAJOR = "1"  # keep in sync with CONFIG_SCHEMA_VERSION

def catalog_schema_ok(path: Path) -> bool:
    data = yaml.safe_load(path.read_text()) or {}
    v = data.get("schema_version")
    return v is None or str(v).strip().split(".")[0] == SUPPORTED_MAJOR

try:
    resolve_catalogs(...)
except BundlerError as e:
    if "Unsupported catalog config schema version" in str(e):
        # prompt upgrade of specify CLI or downgrade of config schema
        ...

When it happens

Trigger: A bundle-catalogs.yml containing 'schema_version: 2.x' (any major != the bundled major) is read during bundle search/install while the installed specify CLI only understands the older major. An absent schema_version stays valid and never raises.

Common situations: Downgrading specify or using an older CLI against a config written by a newer Spec Kit; hand-setting schema_version to a future value; a corrupted or hand-merged file with a bogus version string.

Related errors

• Unsupported catalog config schema version '{str(schema_versi
• Malformed catalog config at {path}: expected a mapping at th
• Malformed catalog config at {config_path}: expected a mappin
• Malformed catalog config at {config_path}: 'catalogs' must b
• Unsupported records schema version '{seen}' at {path}; this

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