github/spec-kit · error · BundlerError

Corrupt records file: {path} — 'bundles' must be a list.

Error message

Corrupt records file: {path} — 'bundles' must be a list.

What it means

Error "Corrupt records file: {path} — 'bundles' must be a list." thrown in github/spec-kit.

Source

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

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")
    if bundles is None:
        bundles = []
    elif not isinstance(bundles, list):
        # `or []` would coerce a FALSY non-list (0, '', False, {}) to [] before
        # this guard, silently treating a corrupt file as "no bundles"; only an
        # absent/None value means empty.
        raise BundlerError(
            f"Corrupt records file: {path} — 'bundles' must be a list."
        )
    return [InstalledBundleRecord.from_dict(item) for item in bundles]


def save_records(project_root: Path, records: list[InstalledBundleRecord]) -> None:
    payload = {
        "schema_version": RECORDS_SCHEMA_VERSION,
        "updated_at": _utc_now(),
        "bundles": [r.to_dict() for r in records],
    }
    dump_json(records_path(project_root), payload, within=project_root)


def find_record(
    records: list[InstalledBundleRecord], bundle_id: str
) -> InstalledBundleRecord | None:
    for record in records:

View on GitHub (pinned to bf88c9f9a8)

Solutions

1. Fix .specify bundle records file: ensure the 'bundles' value is a JSON list, or delete the corrupt records file and reinstall bundles.

When it happens

Trigger: Thrown at src/specify_cli/bundler/models/records.py:136 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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