github/spec-kit · error · BundlerError

Corrupt records file: record for bundle '{bundle_id}' is mis

Error message

Corrupt records file: record for bundle '{bundle_id}' is missing its 'version'.

What it means

Raised by InstalledBundleRecord.from_dict when a record has a valid bundle_id but no usable 'version' (missing, null, or whitespace-only). The version is needed to detect upgrades/downgrades and to attribute installed components, so the record is rejected as corrupt, naming the bundle in the message.

Source

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

        components_raw = data.get("contributed_components")
        if components_raw is None:
            components_raw = []
        elif not isinstance(components_raw, list):
            # `or []` would coerce a FALSY non-list (0, '', False, {}) to []
            # before this guard, silently accepting a corrupt record; only an
            # absent/None value means "no components".
            raise BundlerError(
                "Corrupt record: 'contributed_components' must be a list."
            )
        bundle_id = str(data.get("bundle_id", "")).strip()
        version = str(data.get("version", "")).strip()
        if not bundle_id:
            raise BundlerError(
                "Corrupt records file: an installed-bundle record is missing "
                "its 'bundle_id'."
            )
        if not version:
            raise BundlerError(
                f"Corrupt records file: record for bundle '{bundle_id}' is "
                "missing its 'version'."
            )
        return cls(
            bundle_id=bundle_id,
            version=version,
            installed_at=str(data.get("installed_at", "")).strip(),
            contributed_components=tuple(
                _component_from_dict(c) for c in components_raw
            ),
        )


def records_path(project_root: Path) -> Path:
    return Path(project_root) / ".specify" / RECORDS_FILENAME


def _check_schema_version(value: Any, *, path: Path, required: bool) -> None:

View on GitHub (pinned to bf88c9f9a8)

Solutions

1. Set 'version' to the installed bundle's version string (must match the manifest, e.g. "1.0.0").
2. Remove the record entirely and reinstall the bundle to regenerate correct state.

Example fix

// before
{"bundle_id": "my-bundle", "installed_at": "..."}

// after
{"bundle_id": "my-bundle", "version": "1.0.0", "installed_at": "..."}

def record_has_version(record: dict) -> bool:
    return bool(str(record.get("version", "")).strip())

def is_valid_record(record: object) -> bool:
    return (
        isinstance(record, dict)
        and bool(str(record.get("bundle_id", "")).strip())
        and bool(str(record.get("version", "")).strip())
    )

try:
    records = load_records(project_root)
except BundlerError as e:
    if "missing its 'version'" in str(e):
        # set version to the installed manifest version, or drop the record
        ...

When it happens

Trigger: A records-file entry contains "bundle_id": "my-bundle" but no version key, or "version": "". The second falsy check after bundle_id validation raises.

Common situations: Hand-adding a record while assuming version is optional; stripping fields to shrink the file; older writers that omitted version.

Related errors

• Each installed-bundle record must be a mapping.
• Corrupt record: 'contributed_components' must be a list.
• Corrupt records file: an installed-bundle record is missing
• Corrupt records file: {path}
• Corrupt records file: {path} — missing 'schema_version'. Exp

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