RyanCodrai/turbovec · critical · ValueError

persisted store is corrupt: {len(missing)} {what} id(s) pres

Error message

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

What it means

check_sidecar_keysets cross-checks the id-keyed maps in the JSON side-car (e.g. doc-id to handle vs metadata maps). Every id present in the primary mapping must also appear in the dependent side-car map; missing ids mean the maps were edited or written independently, so loading is aborted with ValueError listing up to three sample ids. The sample is sorted by repr so mixed-type ids (int among strings from a corrupted JSON array) yield ValueError, not TypeError.

Source

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

        what: noun for error messages (e.g. "document", "node").
        mapping_name: side-car field name of the id -> handle map.
        sidecar_name: side-car field name of the id -> payload map.

    Raises:
        ValueError: if either map holds an id the other lacks.
    """
    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

Restore the full side-car (all maps together) from the same backup as the .tvim index.
Rebuild the store from source data if no consistent backup exists.
If repairing manually, add the missing ids to the dependent map — and verify every other keyset check (extraneous ids) also passes.
Pre-validate before load: `set(primary) - set(sidecar_map)` empty; wrap in try/except ValueError for a clean corruption message.

Example fix

// before
# docs map has id "b", meta map lacks it
store = turbovec.load('store.tvim')
// after
missing = set(doc_map) - set(meta_map)
if missing:
    raise RuntimeError(f'side-car maps out of sync: {missing}; restore backup')
store = turbovec.load('store.tvim')

Defensive patterns

Strategy: validation

Validate before calling

def keysets_match(primary, sidecar_map) -> bool:
    return set(primary) == set(sidecar_map)
# compare every id-keyed map pair in the side-car before load

Try / catch

try:
    store = turbovec.load(path)
except ValueError as e:
    if "missing from" in str(e):
        restore_full_sidecar_from_backup()
    else:
        raise

Prevention

Update all side-car maps together through the library API, never one map alone.
Restore the entire side-car file, not individual maps.
Validate keyset equality (set(primary) == set(sidecar)) before loading externally-edited stores.
Treat mixed-type ids in the side-car as corruption: coerce ids to str on write and verify on read.

When it happens

Trigger: load / from_persist_path (or direct check_sidecar_keysets calls) on a side-car whose maps have diverged: an id added to one map but not the other via manual editing, partial writes, or merging files from different saves; also hand-corrupted side-cars holding mixed-type ids (int among strings).

Common situations: Hand-editing the JSON side-car and missing one map; a script updating docs but not metadata maps; restoring only part of the side-car from backup; external corruption inserting a non-string id into a JSON array.

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/12cfc287059572c4. Report an issue: GitHub.