{"record":{"id":"a48fcc09bc73fbe4","repo":"github/spec-kit","slug":"unsupported-catalog-config-schema-version-str-sc-a48fcc","errorCode":null,"errorMessage":"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.","messagePattern":"Unsupported catalog config schema version '(.+?)' at (.+?); this Spec Kit understands version (.+?)\\. The file may have been written by a newer version or is corrupt\\.","errorType":"exception","errorClass":"BundlerError","httpStatus":null,"severity":"error","filePath":"src/specify_cli/bundler/models/catalog.py","lineNumber":293,"sourceCode":"    # aligned the inner non-list ``catalogs`` value between the two readers.\n    data = load_yaml(config_path)\n    if not isinstance(data, dict):\n        raise BundlerError(\n            f\"Malformed catalog config at {config_path}: expected a mapping at \"\n            f\"the top level, got {type(data).__name__}.\"\n        )\n    # Reject an unsupported major schema version, matching the sibling reader\n    # commands_impl/catalog_config._read. Without this, a file written by a\n    # newer/incompatible Spec Kit was silently parsed under v1 assumptions on\n    # the resolution path (bundle search/install), while the other reader\n    # rejected it — the two readers disagreed. An absent schema_version stays\n    # valid (backward compatible with configs that omit it).\n    schema_version = data.get(\"schema_version\")\n    if schema_version is not None and (\n        str(schema_version).strip().split(\".\")[0]\n        != CONFIG_SCHEMA_VERSION.split(\".\")[0]\n    ):\n        raise BundlerError(\n            f\"Unsupported catalog config schema version \"\n            f\"'{str(schema_version).strip()}' at {config_path}; this Spec Kit \"\n            f\"understands version {CONFIG_SCHEMA_VERSION}. The file may have been \"\n            \"written by a newer version or is corrupt.\"\n        )\n    catalogs = data.get(\"catalogs\")\n    if catalogs is None:\n        return\n    if not isinstance(catalogs, list):\n        # Treat only an absent/``None`` ``catalogs`` as \"nothing to merge\"; any\n        # other non-list value (``catalogs: 5``, ``false``, ``0``, ``''``,\n        # ``{}``) is a malformed config and must raise, not be silently skipped\n        # by a falsy check. Otherwise a truthy scalar would raise a raw\n        # ``TypeError: 'int' object is not iterable`` from the loop below, while\n        # falsy non-lists would be swallowed. Report the same actionable\n        # BundlerError the sibling reader of this file raises\n        # (commands_impl/catalog_config.py) so both readers of\n        # bundle-catalogs.yml agree. An empty list stays valid (loop is a no-op).","sourceCodeStart":275,"sourceCodeEnd":311,"githubUrl":"https://github.com/github/spec-kit/blob/bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c/src/specify_cli/bundler/models/catalog.py#L275-L311","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Upgrade Spec Kit ('pip install -U specify-cli' or your package manager) so the CLI understands the file's schema major.","Edit the file's schema_version down to the supported major and adjust any newer-format keys to the v1 layout.","If the file's extra content is not needed, delete it and let the tooling regenerate/ignore it.","Check the sibling reader's supported version (CONFIG_SCHEMA_VERSION) to confirm what major is expected."],"exampleFix":"# before (bundle-catalogs.yml)\nschema_version: 2\ncatalogs: [...]\n\n# after\nschema_version: 1\ncatalogs: [...]","handlingStrategy":"try-catch","validationCode":"import yaml\nfrom pathlib import Path\n\nSUPPORTED_MAJOR = \"1\"  # keep in sync with CONFIG_SCHEMA_VERSION\n\ndef catalog_schema_ok(path: Path) -> bool:\n    data = yaml.safe_load(path.read_text()) or {}\n    v = data.get(\"schema_version\")\n    return v is None or str(v).strip().split(\".\")[0] == SUPPORTED_MAJOR","typeGuard":null,"tryCatchPattern":"try:\n    resolve_catalogs(...)\nexcept BundlerError as e:\n    if \"Unsupported catalog config schema version\" in str(e):\n        # prompt upgrade of specify CLI or downgrade of config schema\n        ...","preventionTips":["Pin the specify CLI version across the team so configs and CLI agree.","Do not hand-edit schema_version to future values.","After upgrading Spec Kit, run a bundle search once in a scratch project to catch schema drift early."],"tags":["bundler","config","schema-version","version-mismatch","catalog"],"backgroundTag":null,"analyzedSha":"bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c","analyzedAt":"2026-08-14T19:43:37.150Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}