RyanCodrai/turbovec · error · ValueError

persisted store at {folder} was saved with distance={recorde

Error message

persisted store at {folder} was saved with distance={recorded!r}, but this store was constructed with distance={self.distance.value!r}. Construct the store with the matching distance to load it.

What it means

Raised in TurboQuantVectorDb._load_from when the v2+ side-car records a distance/similarity mode that conflicts with the mode this store instance was constructed with. The construct-then-create() API means the load cannot silently adopt either mode — vectors written under one scoring mode are invalid under the other.

Source

Thrown at turbovec-python/python/turbovec/agno.py:1237

        )
        if state.get("dimensions") != self.dimensions:
            raise ValueError(
                f"persisted dimensions={state.get('dimensions')} does not "
                f"match this store's embedder dimensions={self.dimensions}"
            )
        # Similarity mode of the persisted vectors. The construct-then-
        # create() API shape means the store already has a mode when the
        # load runs, so a *recorded* mode that conflicts with it is an
        # error — silently adopting either side would surprise someone.
        # A v1 side-car (written before the mode existed) records no
        # mode but holds raw, unnormalized vectors: adopt
        # Distance.max_inner_product — the scoring those stores were
        # written under — and update `self.distance` so introspection
        # reflects how the store actually scores.
        recorded = state.get("distance")
        if recorded is not None:
            if recorded != self.distance.value:
                raise ValueError(
                    f"persisted store at {folder} was saved with "
                    f"distance={recorded!r}, but this store was constructed "
                    f"with distance={self.distance.value!r}. Construct the "
                    f"store with the matching distance to load it."
                )
            distance = self.distance
        else:
            distance = Distance.max_inner_product

        # This is the only in-place load among the four integrations (the
        # others are classmethods returning a fresh object), so it is the
        # only one that can leave a caller holding a half-loaded store.
        # Everything below is therefore built into locals and committed in
        # one block at the end: the validation after the rebuild still
        # raises, and a store whose load raised is one this method never
        # touched (#380).
        index = IdMapIndex.load(str(index_file))
        u64_to_doc = {int(h): d for h, d in state["u64_to_doc"]}

View on GitHub (pinned to ccab9f325e)

Solutions

1. Re-construct the store with the distance= value recorded in the side-car, then load again.
2. Inspect the saved docstore.json's `distance` field to learn the required constructor argument.
3. Catch the ValueError in tooling to report the exact mode mismatch instead of loading mismatched scoring.

When it happens

Trigger: Thrown at turbovec-python/python/turbovec/agno.py:1237 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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