RyanCodrai/turbovec · critical · ValueError

persisted store is corrupt: {len(extraneous)} {what} id(s) p

Error message

persisted store is corrupt: {len(extraneous)} {what} id(s) present in `{sidecar_name}` but missing from `{mapping_name}` (e.g. {sample}). The JSON side-car's maps are out of sync.

What it means

check_sidecar_keysets validates that the JSON side-car's id maps cover exactly the same keys as the main persisted mapping. If the side-car contains ids absent from the mapping (extraneous set), the persisted store is considered corrupt and a ValueError is raised with a sample of up to 3 offending ids. This guards against silent data loss or inconsistency when loading a persisted store.

Source

Thrown at turbovec-python/python/turbovec/_persist.py:517

    mapping_set = set(mapping_keys)
    sidecar_set = set(sidecar_keys)
    if mapping_set == sidecar_set:
        return
    missing = mapping_set - sidecar_set
    if missing:
        # key=repr: a hand-corrupted side-car can hold mixed-type ids
        # (JSON arrays survive parsing with e.g. an int among strings),
        # which plain sorted() would turn into a TypeError instead of
        # the promised ValueError.
        sample = ", ".join(repr(k) for k in sorted(missing, key=repr)[:3])
        raise ValueError(
            f"persisted store is corrupt: {len(missing)} {what} id(s) present "
            f"in `{mapping_name}` but missing from `{sidecar_name}` "
            f"(e.g. {sample}). The JSON side-car's maps are out of sync."
        )
    extraneous = sidecar_set - mapping_set
    sample = ", ".join(repr(k) for k in sorted(extraneous, key=repr)[:3])
    raise ValueError(
        f"persisted store is corrupt: {len(extraneous)} {what} id(s) present "
        f"in `{sidecar_name}` but missing from `{mapping_name}` "
        f"(e.g. {sample}). The JSON side-car's maps are out of sync."
    )


__all__ = ["check_persisted_handles", "check_schema_version", "check_sidecar_keysets"]

View on GitHub (pinned to ccab9f325e)

Solutions

Rebuild the persisted store from source data: re-save the index and side-car atomically with the library's save/persist API instead of loading the corrupt pair.
Remove the extraneous ids from the side-car JSON (or add the corresponding entries to the mapping) so both keysets match exactly.
Restore both the main file and side-car from a consistent backup taken at the same time.
Check for version mismatches between the library version that wrote the store and the one loading it; re-persist with the current version.

Example fix

# before (corrupt side-car with extra id)
sidecar_ids = {1, 2, "3"}; mapping_ids = {1, 2}  # ValueError
# after
# re-persist both files together:
store.save_to_persist_path(path)  # writes mapping + side-car atomically

Defensive patterns

Strategy: validation

Validate before calling

import json
sidecar_ids = set(json.load(open(sidecar_path))['ids'])
mapping_ids = set(store.mapping.keys())
if sidecar_ids != mapping_ids:
    raise ValueError(f"persisted store corrupt: {sidecar_ids ^ mapping_ids}")

Try / catch

try:
    store = TurboStore.from_persist_path(path)
except ValueError as e:
    logger.error("corrupt persisted store: %s", e)
    store = rebuild_store_from_source()

Prevention

Always save the mapping and side-car atomically (temp file + rename) as one unit.
Never hand-edit the persisted JSON files.
Take backups of both files together and restore them together.

When it happens

Trigger: Calling load() or from_persist_path() on a persisted store whose sidecar_name map contains id(s) not present in the mapping_name map; also raised directly by tests that simulate mixed-type ids in the sidecar keyset.

Common situations: Manual editing of the persisted JSON side-car, a partial/interrupted save that wrote the side-car but not the main mapping, an older or newer library version changing the mapping format, or copying/syncing files independently so the two files diverge.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

AI-assisted analysis of RyanCodrai/turbovec@ccab9f325e (2026-09-06). Data as JSON: /api/errors/c29632db22057786. Report an issue: GitHub.