{"record":{"id":"4b4798effe579711","repo":"github/spec-kit","slug":"unsupported-catalog-config-schema-version-str-sc","errorCode":null,"errorMessage":"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.","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/commands_impl/catalog_config.py","lineNumber":58,"sourceCode":"    if not path.exists():\n        return []\n    # ``load_yaml`` returns ``{}`` only for an empty document and the raw parse\n    # otherwise, so a non-mapping top level — a falsy ``[]``/``false``/``0``/``''``\n    # or an explicit null (``load_yaml`` -> ``None``) — is caught by the isinstance\n    # guard below and raised like a truthy one, staying consistent with the other\n    # reader of this file (models/catalog._merge_config).\n    data = load_yaml(path)\n    if not isinstance(data, dict):\n        raise BundlerError(\n            f\"Malformed catalog config at {path}: expected a mapping at the top \"\n            f\"level, got {type(data).__name__}.\"\n        )\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 {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        raise BundlerError(\n            f\"Malformed catalog config at {path}: 'catalogs' must be a list, \"\n            f\"got {type(catalogs).__name__}.\"\n        )\n    for entry in catalogs:\n        if not isinstance(entry, dict):\n            raise BundlerError(\n                f\"Malformed catalog config at {path}: each catalog entry must be \"\n                f\"a mapping, got {type(entry).__name__}.\"","sourceCodeStart":40,"sourceCodeEnd":76,"githubUrl":"https://github.com/github/spec-kit/blob/bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c/src/specify_cli/bundler/commands_impl/catalog_config.py#L40-L76","documentation":"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.","triggerScenarios":"`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).","commonSituations":"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.","solutions":["Align the file's `schema_version` major with the version this CLI understands (shown in the message)","Upgrade spec-kit to the release that wrote the file","Or delete the project-scoped file to fall back to built-in defaults and re-add sources"],"exampleFix":"# before\nschema_version: \"2.0\"\n\n# after\nschema_version: \"1.0\"","handlingStrategy":"validation","validationCode":"from specify_cli.bundler.models.catalog import CONFIG_SCHEMA_VERSION\n\nmajor = str(data.get(\"schema_version\", CONFIG_SCHEMA_VERSION)).strip().split(\".\")[0]\nif major != CONFIG_SCHEMA_VERSION.split(\".\")[0]:\n    raise SystemExit(f\"config schema {major}.x not understood; CLI knows {CONFIG_SCHEMA_VERSION}\")","typeGuard":"def schema_major_matches(data: dict) -> bool:\n    v = data.get(\"schema_version\")\n    return v is None or str(v).strip().split(\".\")[0] == CONFIG_SCHEMA_VERSION.split(\".\")[0]","tryCatchPattern":"try:\n    read_catalog_config(project_root)\nexcept BundlerError as exc:\n    if \"Unsupported catalog config schema version\" in str(exc):\n        # upgrade spec-kit or regenerate the project-scoped file\n        raise\n    raise","preventionTips":["Pin the spec-kit version in CI so schema versions stay aligned across the team","After upgrading spec-kit, check bundle-catalogs.yml schema_version against the release notes"],"tags":["bundler","catalog","schema-version","version-mismatch"],"backgroundTag":null,"analyzedSha":"bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c","analyzedAt":"2026-08-14T19:43:37.150Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}