RyanCodrai/turbovec · error · ValueError

persisted dimensions={state.get('dimensions')} does not matc

Error message

persisted dimensions={state.get('dimensions')} does not match this store's embedder dimensions={self.dimensions}

What it means

Raised in TurboQuantVectorDb._load_from when the persisted side-car's `dimensions` field differs from self.dimensions (the dimension implied by the embedder passed to this store instance). The saved index was built with a different embedder size, so its vectors cannot be searched with this instance's configuration.

Source

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

            )

    def _load_from(self, folder: Path) -> None:
        side_car = folder / _STORE_FILENAME
        index_file = folder / _INDEX_FILENAME
        if not side_car.exists() or not index_file.exists():
            raise FileNotFoundError(
                f"missing one of {_STORE_FILENAME}/{_INDEX_FILENAME} under {folder}"
            )
        with open(side_car) as f:
            state = json.load(f)
        version = state.get("schema_version", 0)
        check_schema_version(
            version,
            _DOCSTORE_SCHEMA_COMPAT,
            prefix=f"{_STORE_FILENAME} has schema_version",
        )
        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 "

View on GitHub (pinned to ccab9f325e)

Solutions

1. Construct the store with the embedder whose dimension matches the persisted state (compare state['dimensions'] with the embedder's output size).
2. Rebuild the store from source documents if the embedder has intentionally changed.
3. Catch the ValueError to surface a clear 'wrong embedder for this saved store' configuration error to users.

When it happens

Trigger: Thrown at turbovec-python/python/turbovec/agno.py:1221 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/896d058d901dcc39. Report an issue: GitHub.