{"record":{"id":"c70bf036be3ffc3d","repo":"github/spec-kit","slug":"unsupported-records-schema-version-seen-at-pa","errorCode":null,"errorMessage":"Unsupported records schema version '{seen}' at {path}; this Spec Kit understands version {RECORDS_SCHEMA_VERSION}. The file may have been written by a newer version or is corrupt.","messagePattern":"Unsupported records 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/records.py","lineNumber":111,"sourceCode":"\ndef _check_schema_version(value: Any, *, path: Path, required: bool) -> None:\n    \"\"\"Reject a records file whose schema version we cannot safely parse.\n\n    A future incompatible format (or a corrupted file) must fail fast with an\n    actionable error rather than being silently mis-parsed, which could lead to\n    incorrect bundle attribution or removal. Forward-compatible minor bumps that\n    keep the same major version are accepted.\n    \"\"\"\n    if value is None:\n        if required:\n            raise BundlerError(\n                f\"Corrupt records file: {path} — missing 'schema_version'. \"\n                f\"Expected version {RECORDS_SCHEMA_VERSION}.\"\n            )\n        return\n    seen = str(value).strip()\n    if seen.split(\".\")[0] != RECORDS_SCHEMA_VERSION.split(\".\")[0]:\n        raise BundlerError(\n            f\"Unsupported records schema version '{seen}' at {path}; this \"\n            f\"Spec Kit understands version {RECORDS_SCHEMA_VERSION}. The file may \"\n            \"have been written by a newer version or is corrupt.\"\n        )\n\n\ndef load_records(project_root: Path) -> list[InstalledBundleRecord]:\n    # Defense in depth (mirrors the write path's within= confinement): refuse to\n    # read through a symlinked or traversal-escaping ``.specify`` that resolves\n    # outside project_root.\n    path = ensure_within(project_root, records_path(project_root))\n    if not path.exists():\n        return []\n    data = load_json(path)\n    if not isinstance(data, dict):\n        raise BundlerError(f\"Corrupt records file: {path}\")\n    _check_schema_version(data.get(\"schema_version\"), path=path, required=True)\n    bundles = data.get(\"bundles\")","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/github/spec-kit/blob/bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c/src/specify_cli/bundler/models/records.py#L93-L129","documentation":"Raised by _check_schema_version when the records file declares a schema_version whose major component differs from RECORDS_SCHEMA_VERSION understood by the running Spec Kit. Forward-compatible minor bumps within the same major are accepted; a different major is rejected as either newer-tool output or corruption, preventing mis-attribution during uninstall.","triggerScenarios":"load_records reads a records file with \"schema_version\": \"2.0\" while the CLI supports major 1 (or vice versa after a downgrade). The split('.')[0] major comparison fails and raises with the seen value and supported version in the message.","commonSituations":"Opening a project written by a newer Spec Kit with an older CLI; mixed toolchain versions across a team; hand-bumping the version string.","solutions":["Upgrade Spec Kit to a version that supports the records schema major shown in the error.","Or downgrade the file: set schema_version to the supported major and verify record fields match the older format.","Or delete the records file and reinstall bundles to rebuild state under the current schema."],"exampleFix":"// before\n{\"schema_version\": \"2\", \"bundles\": [...]}\n\n// after\n{\"schema_version\": \"1\", \"bundles\": [...]}","handlingStrategy":"try-catch","validationCode":"SUPPORTED_RECORDS_MAJOR = \"1\"\n\ndef records_schema_supported(data: dict) -> bool:\n    v = data.get(\"schema_version\")\n    return v is not None and str(v).strip().split(\".\")[0] == SUPPORTED_RECORDS_MAJOR","typeGuard":null,"tryCatchPattern":"try:\n    records = load_records(project_root)\nexcept BundlerError as e:\n    if \"Unsupported records schema version\" in str(e):\n        # upgrade specify CLI, or rebuild records under the current schema\n        ...","preventionTips":["Keep one specify version pinned across the team/machine.","After upgrading Spec Kit, run a bundle list to surface schema mismatches immediately.","Minor bumps within the same major are safe; major changes require migration."],"tags":["bundler","records","schema-version","version-mismatch","json"],"backgroundTag":null,"analyzedSha":"bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c","analyzedAt":"2026-08-14T19:43:37.150Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}