{"record":{"id":"fa8f588c35d7ba61","repo":"HKUDS/DeepTutor","slug":"this-knowledge-base-was-indexed-with-faiss-but-the","errorCode":null,"errorMessage":"This knowledge base was indexed with FAISS but the 'faiss-cpu' package is not installed. Install it (pip install faiss-cpu) or re-index the knowledge base to query it again.","messagePattern":"This knowledge base was indexed with FAISS but the 'faiss-cpu' package is not installed\\. Install it \\(pip install faiss-cpu\\) or re-index the knowledge base to query it again\\.","errorType":"error_code","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"deeptutor/services/rag/pipelines/llamaindex/vector_store.py","lineNumber":238,"sourceCode":"            head = handle.read(1)\n    except OSError:\n        return BACKEND_SIMPLE\n    return BACKEND_SIMPLE if head[:1] == b\"{\" else BACKEND_FAISS\n\n\ndef load_index(storage_dir: Path) -> Any:\n    \"\"\"Load a persisted index for retrieval.\n\n    FAISS-persisted versions load their binary index directly. Legacy\n    SimpleVectorStore versions load unchanged and stay queryable; re-indexing\n    such a knowledge base rebuilds it as FAISS for the full speed-up.\n    \"\"\"\n    storage_dir = Path(storage_dir)\n\n    if detect_backend(storage_dir) == BACKEND_FAISS:\n        cosine_cls = _cosine_faiss_cls()\n        if cosine_cls is None:\n            raise RuntimeError(\n                \"This knowledge base was indexed with FAISS but the 'faiss-cpu' \"\n                \"package is not installed. Install it (pip install faiss-cpu) or \"\n                \"re-index the knowledge base to query it again.\"\n            )\n        vector_store = cosine_cls.from_persist_dir(str(storage_dir))\n        context = StorageContext.from_defaults(\n            persist_dir=str(storage_dir), vector_store=vector_store\n        )\n        return load_index_from_storage(context)\n\n    context = StorageContext.from_defaults(persist_dir=str(storage_dir))\n    return load_index_from_storage(context)\n\n\n__all__ = [\n    \"BACKEND_FAISS\",\n    \"BACKEND_SIMPLE\",\n    \"DEFAULT_VECTOR_STORE_FILENAME\",","sourceCodeStart":220,"sourceCodeEnd":256,"githubUrl":"https://github.com/HKUDS/DeepTutor/blob/3e82f130422a813cdd73c10b21a44e9325f5821a/deeptutor/services/rag/pipelines/llamaindex/vector_store.py#L220-L256","documentation":"load_index() detects a FAISS backend marker in the KB's storage directory but the faiss-cpu import failed (the cosine FAISS class factory returned None). The KB is unreadable until faiss-cpu is installed or the KB is re-indexed with the default simple vector store.","triggerScenarios":"Calling load_index() on a storage_dir whose persist metadata indicates BACKEND_FAISS while the faiss-cpu package is absent from the environment (CLI-only or slim install without the faiss extra).","commonSituations":"Indexing on a machine with faiss-cpu, then querying on a slim Docker image / deeptutor-cli install without it; upgrading or recreating a venv that dropped faiss-cpu.","solutions":["pip install faiss-cpu in the active environment, then retry load_index().","If you can't install native deps, re-index the KB so it persists with the fallback simple vector store instead of FAISS.","Pin faiss-cpu in requirements/pyproject for deployments that will query FAISS-backed KBs."],"exampleFix":"# before\nindex = load_index(storage_dir=kb_path)  # RuntimeError: faiss-cpu not installed\n\n# after\n# shell: pip install faiss-cpu\nindex = load_index(storage_dir=kb_path)","handlingStrategy":"fallback","validationCode":"def faiss_available() -> bool:\n    try:\n        import faiss  # noqa: F401\n        return True\n    except ImportError:\n        return False","typeGuard":"def can_load_faiss_backend(storage_dir) -> bool:\n    from deeptutor.services.rag.pipelines.llamaindex.vector_store import detect_backend, BACKEND_FAISS\n    return not (detect_backend(storage_dir) == BACKEND_FAISS and not faiss_available())","tryCatchPattern":"try:\n    index = load_index(storage_dir=d)\nexcept RuntimeError as e:\n    if \"faiss-cpu\" in str(e):\n        subprocess.run([sys.executable, \"-m\", \"pip\", \"install\", \"faiss-cpu\"], check=True)\n        index = load_index(storage_dir=d)\n    else:\n        raise","preventionTips":["Install faiss-cpu in every environment that queries FAISS-backed KBs.","Pin faiss-cpu in deployment requirements.","Add an import check at app startup when FAISS KBs are expected."],"tags":["faiss","missing-dependency","rag","vector-store"],"backgroundTag":"missing-optional-dependency","analyzedSha":"3e82f130422a813cdd73c10b21a44e9325f5821a","analyzedAt":"2026-08-27T06:57:25.364Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}