{"record":{"id":"b659f949d0bd4d14","repo":"HKUDS/DeepTutor","slug":"no-existing-faiss-index-found-at-persist-path","errorCode":null,"errorMessage":"No existing FAISS index found at {persist_path}.","messagePattern":"No existing FAISS index found at (.+?)\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"deeptutor/services/rag/pipelines/llamaindex/vector_store.py","lineNumber":162,"sourceCode":"                query.query_embedding = _normalize(query.query_embedding)\n            return super().query(query, **kwargs)\n\n        def persist(self, persist_path: str, fs: Any = None) -> None:\n            if fs is not None and not isinstance(fs, LocalFileSystem):\n                raise NotImplementedError(\"FAISS only supports local storage for now.\")\n            dirpath = os.path.dirname(persist_path)\n            if dirpath:\n                os.makedirs(dirpath, exist_ok=True)\n            faiss_write_index(self._faiss_index, persist_path)\n\n        @classmethod\n        def from_persist_path(cls, persist_path: str, fs: Any = None) -> Any:\n            if fs is not None and not isinstance(fs, LocalFileSystem):\n                raise NotImplementedError(\"FAISS only supports local storage for now.\")\n            if not os.path.exists(persist_path):\n                raise ValueError(f\"No existing FAISS index found at {persist_path}.\")\n            return cls(faiss_index=faiss_read_index(persist_path))\n\n    _COSINE_FAISS_CLS = _CosineFaissVectorStore\n    return _COSINE_FAISS_CLS\n\n\ndef _uniform_dimension(embeddings: Iterable[Any]) -> Optional[int]:\n    \"\"\"Return the shared embedding dimension, or None if missing/ragged.\n\n    Mixed dimensions (e.g. text + multimodal image vectors) cannot live in a\n    single fixed-width FAISS index, so callers fall back to SimpleVectorStore.\n    \"\"\"\n    dimension: Optional[int] = None\n    for embedding in embeddings:\n        if embedding is None:\n            return None\n        length = len(embedding)\n        if dimension is None:\n            dimension = length\n        elif length != dimension:","sourceCodeStart":144,"sourceCodeEnd":180,"githubUrl":"https://github.com/HKUDS/DeepTutor/blob/3e82f130422a813cdd73c10b21a44e9325f5821a/deeptutor/services/rag/pipelines/llamaindex/vector_store.py#L144-L180","documentation":"Raised by the internal cosine FAISS vector-store class factory's from_persist_path when the requested FAISS index file does not exist on local disk. It prevents faiss_read_index from being called on a missing file and producing a lower-level deserialization error.","triggerScenarios":"Calling load_index() or new_faiss_storage_context() (which route through _cosine_faiss_cls().from_persist_path) with a persist_path that was never written, e.g., querying a KB before it was indexed, or a deleted/moved storage directory.","commonSituations":"Fresh KB queried before the first add_documents, storage directory wiped or on a different machine, path typos, or a failed prior indexing run that never persisted the FAISS file.","solutions":["Verify the file exists: ls <persist_path>; if missing, run add_documents to build and persist the index.","Confirm you're pointing at the right storage_dir for the KB (check kb list output / settings).","If a prior indexing run crashed before persisting, re-index the knowledge base."],"exampleFix":"# before\nvector_store = cosine_cls.from_persist_path(\"data/user/kbs/my-kb/faiss.index\")  # ValueError\n\n# after\nimport os\npath = \"data/user/kbs/my-kb/faiss.index\"\nif not os.path.exists(path):\n    pipeline.add_documents(kb=\"my-kb\", documents=docs)  # build + persist\nvector_store = cosine_cls.from_persist_path(path)","handlingStrategy":"validation","validationCode":"import os\nif not os.path.exists(persist_path):\n    raise FileNotFoundError(f\"index not built yet: {persist_path}\")","typeGuard":"def has_faiss_index(persist_path: str) -> bool:\n    import os\n    return os.path.isfile(persist_path) and os.path.getsize(persist_path) > 0","tryCatchPattern":"try:\n    store = cosine_cls.from_persist_path(persist_path)\nexcept ValueError as e:\n    if \"No existing FAISS index\" in str(e):\n        pipeline.add_documents(...)  # build then retry\n    else:\n        raise","preventionTips":["Check KB status is 'indexed' before issuing queries.","Ensure indexing completes (no crash) before first query.","Use canonical KB storage paths from kb list rather than hand-built strings."],"tags":["faiss","vector-store","file-not-found","rag"],"backgroundTag":"index-file-missing","analyzedSha":"3e82f130422a813cdd73c10b21a44e9325f5821a","analyzedAt":"2026-08-27T06:57:25.364Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}