{"record":{"id":"b9e94ba4130e680d","repo":"github/spec-kit","slug":"corrupt-records-file-path-missing-schema-ver","errorCode":null,"errorMessage":"Corrupt records file: {path} — missing 'schema_version'. Expected version {RECORDS_SCHEMA_VERSION}.","messagePattern":"Corrupt records file: (.+?) — missing 'schema_version'\\. Expected version (.+?)\\.","errorType":"exception","errorClass":"BundlerError","httpStatus":null,"severity":"error","filePath":"src/specify_cli/bundler/models/records.py","lineNumber":104,"sourceCode":"            ),\n        )\n\n\ndef records_path(project_root: Path) -> Path:\n    return Path(project_root) / \".specify\" / RECORDS_FILENAME\n\n\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))","sourceCodeStart":86,"sourceCodeEnd":122,"githubUrl":"https://github.com/github/spec-kit/blob/bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c/src/specify_cli/bundler/models/records.py#L86-L122","documentation":"Raised by _check_schema_version when the installed-bundles records file (a JSON file under .specify) lacks 'schema_version' and the caller marked it required (load_records does). The version gate exists so a future incompatible format fails fast with an actionable error instead of being silently mis-parsed, which could cause incorrect bundle attribution or removal.","triggerScenarios":"load_records(project_root) reads an existing records file whose top-level object has no 'schema_version' key; required=True makes the None branch raise. (Other callers may pass required=False for lenient contexts.)","commonSituations":"Records written by an early/prototype writer that omitted schema_version; hand-created files; files from a downgraded tool version predating the version gate.","solutions":["Add \"schema_version\": \"<RECORDS_SCHEMA_VERSION>\" (the major your CLI supports, e.g. \"1\") to the top level of the records file.","If record contents may be stale, delete the file and reinstall bundles to regenerate it.","Upgrade Spec Kit if a newer version understands the file's origin format."],"exampleFix":"// before\n{\"bundles\": [...]}\n\n// after\n{\"schema_version\": \"1\", \"bundles\": [...]}","handlingStrategy":"validation","validationCode":"import json\nfrom pathlib import Path\n\nSUPPORTED_RECORDS_MAJOR = \"1\"  # keep in sync with RECORDS_SCHEMA_VERSION\n\ndef records_has_schema_version(path: Path) -> bool:\n    data = json.loads(path.read_text())\n    return data.get(\"schema_version\") is not None","typeGuard":null,"tryCatchPattern":"try:\n    records = load_records(project_root)\nexcept BundlerError as e:\n    if \"missing 'schema_version'\" in str(e):\n        # add the supported schema_version, or rebuild the file via reinstall\n        ...","preventionTips":["Any tool that writes the records file must stamp schema_version.","Prefer regenerating state over hand-patching missing headers."],"tags":["bundler","records","json","schema-version","corruption"],"backgroundTag":null,"analyzedSha":"bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c","analyzedAt":"2026-08-14T19:43:37.150Z","schemaVersion":2},"datasetVersion":"2026-08-16T03:17:38.424Z"}