HKUDS/DeepTutor · error · ValueError

No existing FAISS index found at {persist_path}.

Error message

No existing FAISS index found at {persist_path}.

What it means

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.

Source

Thrown at deeptutor/services/rag/pipelines/llamaindex/vector_store.py:162

                query.query_embedding = _normalize(query.query_embedding)
            return super().query(query, **kwargs)

        def persist(self, persist_path: str, fs: Any = None) -> None:
            if fs is not None and not isinstance(fs, LocalFileSystem):
                raise NotImplementedError("FAISS only supports local storage for now.")
            dirpath = os.path.dirname(persist_path)
            if dirpath:
                os.makedirs(dirpath, exist_ok=True)
            faiss_write_index(self._faiss_index, persist_path)

        @classmethod
        def from_persist_path(cls, persist_path: str, fs: Any = None) -> Any:
            if fs is not None and not isinstance(fs, LocalFileSystem):
                raise NotImplementedError("FAISS only supports local storage for now.")
            if not os.path.exists(persist_path):
                raise ValueError(f"No existing FAISS index found at {persist_path}.")
            return cls(faiss_index=faiss_read_index(persist_path))

    _COSINE_FAISS_CLS = _CosineFaissVectorStore
    return _COSINE_FAISS_CLS


def _uniform_dimension(embeddings: Iterable[Any]) -> Optional[int]:
    """Return the shared embedding dimension, or None if missing/ragged.

    Mixed dimensions (e.g. text + multimodal image vectors) cannot live in a
    single fixed-width FAISS index, so callers fall back to SimpleVectorStore.
    """
    dimension: Optional[int] = None
    for embedding in embeddings:
        if embedding is None:
            return None
        length = len(embedding)
        if dimension is None:
            dimension = length
        elif length != dimension:

View on GitHub (pinned to 3e82f13042)

Solutions

  1. Verify the file exists: ls <persist_path>; if missing, run add_documents to build and persist the index.
  2. Confirm you're pointing at the right storage_dir for the KB (check kb list output / settings).
  3. If a prior indexing run crashed before persisting, re-index the knowledge base.

Example fix

# before
vector_store = cosine_cls.from_persist_path("data/user/kbs/my-kb/faiss.index")  # ValueError

# after
import os
path = "data/user/kbs/my-kb/faiss.index"
if not os.path.exists(path):
    pipeline.add_documents(kb="my-kb", documents=docs)  # build + persist
vector_store = cosine_cls.from_persist_path(path)
Defensive patterns

Strategy: validation

Validate before calling

import os
if not os.path.exists(persist_path):
    raise FileNotFoundError(f"index not built yet: {persist_path}")

Type guard

def has_faiss_index(persist_path: str) -> bool:
    import os
    return os.path.isfile(persist_path) and os.path.getsize(persist_path) > 0

Try / catch

try:
    store = cosine_cls.from_persist_path(persist_path)
except ValueError as e:
    if "No existing FAISS index" in str(e):
        pipeline.add_documents(...)  # build then retry
    else:
        raise

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of HKUDS/DeepTutor@3e82f13042 (2026-08-27). Data as JSON: /api/errors/b659f949d0bd4d14. Report an issue: GitHub.