RyanCodrai/turbovec · error · RuntimeError

TurboQuantVectorDb has no index to save — call create() firs

Error message

TurboQuantVectorDb has no index to save — call create() first.

What it means

Raised in TurboQuantVectorDb.save when self._index is None — i.e. create() was never called and no vectors have been added, so there is no quantized index payload to persist. It prevents writing an empty/broken store that a later load would fail on.

Source

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

    def save(self, folder_path: Optional[str] = None) -> None:
        """Persist the quantized index plus a JSON side-car to disk. Pass
        ``folder_path`` to override the constructor's ``path=``.

        Writes two files under ``folder_path``:
          - ``index.tvim`` — the :class:`IdMapIndex` payload.
          - ``docstore.json`` — JSON-encoded document text, metadata, and
            id maps. Side-car carries a ``schema_version`` field; loaders
            reject unknown versions rather than silently misinterpreting
            bytes.
        """
        path = folder_path if folder_path is not None else self.path
        if path is None:
            raise ValueError(
                "No path to save to. Pass `folder_path=` here or set "
                "`path=` on the constructor."
            )
        if self._index is None:
            raise RuntimeError(
                "TurboQuantVectorDb has no index to save — call create() first."
            )
        folder = Path(path)
        folder.mkdir(parents=True, exist_ok=True)
        # Serializes with writers: snapshotting the maps and the index
        # concurrently with a write would persist a torn store to disk.
        # Reads may proceed while a save runs.
        with self._write_lock:
            payload = {
                "schema_version": _DOCSTORE_SCHEMA_VERSION,
                # Round-trip int handles via list-of-pairs (JSON keys must be
                # strings, but our handles are ints).
                "u64_to_doc": [[h, d] for h, d in self._u64_to_doc.items()],
                "next_u64": self._next_u64,
                "bit_width": self.bit_width,
                "dimensions": self.dimensions,
                # Recorded so a later create()/load restores the mode the
                # vectors were written under (v2+).

View on GitHub (pinned to ccab9f325e)

Solutions

1. Call create() (which builds/locks the index) before save().
2. Ensure at least one insert/upsert has run so the index exists, then save.
3. Guard persistence code with `if store._index is not None` or catch the RuntimeError to skip saving empty stores.

When it happens

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