RyanCodrai/turbovec · error · NotImplementedError

fsspec filesystems are not supported yet; pass a local path.

Error message

fsspec filesystems are not supported yet; pass a local path.

What it means

persist() does not support fsspec filesystem objects (s3://, gcs://, etc.). Only local filesystem paths are implemented, so passing fs=None is required; any non-None fs raises this NotImplementedError from the documented constraint.

Source

Thrown at turbovec-python/python/turbovec/llama_index.py:1001

    def persist(self, persist_path: str, fs: Any = None) -> None:
        """Persist the store. ``persist_path`` is treated as a path *stem*:
        the binary index goes to ``{stem}.tvim`` and the node side-car to
        ``{stem}.nodes.json``. A trailing ``.json`` extension (the
        StorageContext default) is stripped from ``persist_path`` first;
        dots anywhere else in the name (e.g. a dotted namespace like
        ``v1.2``) are preserved verbatim, so dotted namespaces sharing a
        prefix persist to distinct file pairs (issue #200).

        This matches the layout assumed by ``StorageContext.persist`` —
        which calls us with ``persist_path = {persist_dir}/{namespace}__vector_store.json`` —
        and lets multiple namespaced stores coexist in the same directory.

        Node metadata must be JSON-serializable (same constraint as
        ``SimpleVectorStore``). ``fs`` (fsspec) is not yet supported;
        pass a local path.
        """
        if fs is not None:
            raise NotImplementedError(
                "fsspec filesystems are not supported yet; pass a local path."
            )
        base = _split_persist_base(persist_path)
        base.parent.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 persist runs.
        with self._write_lock:
            payload = {
                "schema_version": _NODES_SCHEMA_VERSION,
                "nodes": self._nodes,
                # JSON object keys must be strings; round-trip int keys via
                # an explicit list of [node_id, handle] pairs to preserve
                # type fidelity.
                "node_id_to_u64": list(self._node_id_to_u64.items()),
                "next_u64": self._next_u64,
                # Recorded so `from_persist_path` restores the mode the
                # vectors were written under (v3+).

View on GitHub (pinned to ccab9f325e)

Solutions

1. Pass fs=None (omit it) and persist to a local path.
2. Persist locally first, then upload the resulting files to remote storage yourself.
3. Wait for / contribute fsspec support upstream.

Example fix

// before
store.persist("s3://bucket/vecstore", fs=s3fs.S3FileSystem())
// after
store.persist("/tmp/vecstore")
# then upload /tmp/vecstore/* to s3://bucket/vecstore
fs.put("/tmp/vecstore", "bucket/vecstore", recursive=True)

if fs is not None:
    raise ValueError("persist to a local path; upload manually afterwards")

try:
    store.persist(path, fs=fs)
except NotImplementedError:
    store.persist(local_path)
    upload_to_remote(local_path)

When it happens

Trigger: Calling store.persist(persist_path="s3://bucket/store", fs=s3fs) or any persist call with a non-None fs argument.

Common situations: Persisting to cloud storage in a pipeline that previously used llama_index's SimpleVectorStore (which supports fsspec); swapping store implementations without noticing the fs capability gap.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• persisted store is corrupt: duplicate node handles in the si
• duplicate node_id {dup!r} appears multiple times in the inpu
• TurboQuantVectorStore.get(text_id) cannot return the origina
• filter condition {condition!r} not supported by TurboQuantVe
• filter operator {op!r} not supported by TurboQuantVectorStor

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