github/spec-kit · error · BundlerError

Unsupported records schema version '{seen}' at {path}; this

Error message

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.

What it means

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.

Source

Thrown at src/specify_cli/bundler/models/records.py:111

def _check_schema_version(value: Any, *, path: Path, required: bool) -> None:
    """Reject a records file whose schema version we cannot safely parse.

    A future incompatible format (or a corrupted file) must fail fast with an
    actionable error rather than being silently mis-parsed, which could lead to
    incorrect bundle attribution or removal. Forward-compatible minor bumps that
    keep the same major version are accepted.
    """
    if value is None:
        if required:
            raise BundlerError(
                f"Corrupt records file: {path} — missing 'schema_version'. "
                f"Expected version {RECORDS_SCHEMA_VERSION}."
            )
        return
    seen = str(value).strip()
    if seen.split(".")[0] != RECORDS_SCHEMA_VERSION.split(".")[0]:
        raise BundlerError(
            f"Unsupported records schema version '{seen}' at {path}; this "
            f"Spec Kit understands version {RECORDS_SCHEMA_VERSION}. The file may "
            "have been written by a newer version or is corrupt."
        )


def load_records(project_root: Path) -> list[InstalledBundleRecord]:
    # Defense in depth (mirrors the write path's within= confinement): refuse to
    # read through a symlinked or traversal-escaping ``.specify`` that resolves
    # outside project_root.
    path = ensure_within(project_root, records_path(project_root))
    if not path.exists():
        return []
    data = load_json(path)
    if not isinstance(data, dict):
        raise BundlerError(f"Corrupt records file: {path}")
    _check_schema_version(data.get("schema_version"), path=path, required=True)
    bundles = data.get("bundles")

View on GitHub (pinned to bf88c9f9a8)

Solutions

  1. Upgrade Spec Kit to a version that supports the records schema major shown in the error.
  2. Or downgrade the file: set schema_version to the supported major and verify record fields match the older format.
  3. Or delete the records file and reinstall bundles to rebuild state under the current schema.

Example fix

// before
{"schema_version": "2", "bundles": [...]}

// after
{"schema_version": "1", "bundles": [...]}
Defensive patterns

Strategy: try-catch

Validate before calling

SUPPORTED_RECORDS_MAJOR = "1"

def records_schema_supported(data: dict) -> bool:
    v = data.get("schema_version")
    return v is not None and str(v).strip().split(".")[0] == SUPPORTED_RECORDS_MAJOR

Try / catch

try:
    records = load_records(project_root)
except BundlerError as e:
    if "Unsupported records schema version" in str(e):
        # upgrade specify CLI, or rebuild records under the current schema
        ...

Prevention

When it happens

Trigger: 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.

Common situations: Opening a project written by a newer Spec Kit with an older CLI; mixed toolchain versions across a team; hand-bumping the version string.

Related errors

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