{"record":{"id":"4ff75501f428fa3c","repo":"RyanCodrai/turbovec","slug":"fsspec-filesystems-are-not-supported-yet-pass-a-l","errorCode":null,"errorMessage":"fsspec filesystems are not supported yet; pass a local path.","messagePattern":"fsspec filesystems are not supported yet; pass a local path\\.","errorType":"exception","errorClass":"NotImplementedError","httpStatus":null,"severity":"error","filePath":"turbovec-python/python/turbovec/llama_index.py","lineNumber":1001,"sourceCode":"    def persist(self, persist_path: str, fs: Any = None) -> None:\n        \"\"\"Persist the store. ``persist_path`` is treated as a path *stem*:\n        the binary index goes to ``{stem}.tvim`` and the node side-car to\n        ``{stem}.nodes.json``. A trailing ``.json`` extension (the\n        StorageContext default) is stripped from ``persist_path`` first;\n        dots anywhere else in the name (e.g. a dotted namespace like\n        ``v1.2``) are preserved verbatim, so dotted namespaces sharing a\n        prefix persist to distinct file pairs (issue #200).\n\n        This matches the layout assumed by ``StorageContext.persist`` —\n        which calls us with ``persist_path = {persist_dir}/{namespace}__vector_store.json`` —\n        and lets multiple namespaced stores coexist in the same directory.\n\n        Node metadata must be JSON-serializable (same constraint as\n        ``SimpleVectorStore``). ``fs`` (fsspec) is not yet supported;\n        pass a local path.\n        \"\"\"\n        if fs is not None:\n            raise NotImplementedError(\n                \"fsspec filesystems are not supported yet; pass a local path.\"\n            )\n        base = _split_persist_base(persist_path)\n        base.parent.mkdir(parents=True, exist_ok=True)\n        # Serializes with writers: snapshotting the maps and the index\n        # concurrently with a write would persist a torn store to disk.\n        # Reads may proceed while a persist runs.\n        with self._write_lock:\n            payload = {\n                \"schema_version\": _NODES_SCHEMA_VERSION,\n                \"nodes\": self._nodes,\n                # JSON object keys must be strings; round-trip int keys via\n                # an explicit list of [node_id, handle] pairs to preserve\n                # type fidelity.\n                \"node_id_to_u64\": list(self._node_id_to_u64.items()),\n                \"next_u64\": self._next_u64,\n                # Recorded so `from_persist_path` restores the mode the\n                # vectors were written under (v3+).","sourceCodeStart":983,"sourceCodeEnd":1019,"githubUrl":"https://github.com/RyanCodrai/turbovec/blob/ccab9f325e6ce2a270a87daf01ae4e443bcf2d49/turbovec-python/python/turbovec/llama_index.py#L983-L1019","documentation":"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.","triggerScenarios":"Calling store.persist(persist_path=\"s3://bucket/store\", fs=s3fs) or any persist call with a non-None fs argument.","commonSituations":"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.","solutions":["Pass fs=None (omit it) and persist to a local path.","Persist locally first, then upload the resulting files to remote storage yourself.","Wait for / contribute fsspec support upstream."],"exampleFix":"// before\nstore.persist(\"s3://bucket/vecstore\", fs=s3fs.S3FileSystem())\n// after\nstore.persist(\"/tmp/vecstore\")\n# then upload /tmp/vecstore/* to s3://bucket/vecstore\nfs.put(\"/tmp/vecstore\", \"bucket/vecstore\", recursive=True)","handlingStrategy":"validation","validationCode":"if fs is not None:\n    raise ValueError(\"persist to a local path; upload manually afterwards\")","typeGuard":null,"tryCatchPattern":"try:\n    store.persist(path, fs=fs)\nexcept NotImplementedError:\n    store.persist(local_path)\n    upload_to_remote(local_path)","preventionTips":["Keep persist/load paths local in the turbovec integration.","Handle cloud sync as a separate post-persist step.","Check the docstring: fs support is explicitly not implemented."],"tags":["python","llama-index","persist","fsspec","unsupported-feature"],"backgroundTag":"unsupported-operation","analyzedSha":"ccab9f325e6ce2a270a87daf01ae4e443bcf2d49","analyzedAt":"2026-09-06T08:39:18.516Z","contentChangedAt":"2026-09-06T08:39:18.516Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}