github/spec-kit · error · BundlerError

Corrupt records file: an installed-bundle record is missing

Error message

Corrupt records file: an installed-bundle record is missing its 'bundle_id'.

What it means

Raised by InstalledBundleRecord.from_dict when a record object has no usable 'bundle_id' — the value is missing, null, or whitespace-only after str().strip(). bundle_id is the primary key used for bundle attribution and uninstall targeting, so a record without it cannot be honored.

Source

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

    @classmethod
    def from_dict(cls, data: Any) -> "InstalledBundleRecord":
        if not isinstance(data, dict):
            raise BundlerError("Each installed-bundle record must be a mapping.")
        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
            ),
        )

View on GitHub (pinned to bf88c9f9a8)

Solutions

1. Add the correct 'bundle_id' string to the record.
2. If the bundle is not actually installed, delete the entire record entry.
3. Reinstall the bundle to let Spec Kit write a fresh, valid record.

Example fix

// before
{"version": "1.0.0", "installed_at": "...", "contributed_components": []}

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

def record_has_bundle_id(record: dict) -> bool:
    return bool(str(record.get("bundle_id", "")).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 'bundle_id'" in str(e):
        # remove the anonymous record or restore its bundle_id
        ...

When it happens

Trigger: A records-file entry lacks the 'bundle_id' key, has "bundle_id": "", or "bundle_id": " ". The falsy check after strip() raises with a file-level 'Corrupt records file' message.

Common situations: Hand-trimming a record and deleting the wrong key; a merge conflict resolution that drops the line; a bug in external tooling that wrote the file.

Related errors

• Each installed-bundle record must be a mapping.
• Corrupt record: 'contributed_components' must be a list.
• Corrupt records file: record for bundle '{bundle_id}' is mis
• 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/f3615624380f2b8f. Report an issue: GitHub.