{"record":{"id":"fc358bc31a9d66d4","repo":"HKUDS/DeepTutor","slug":"rag-index-contains-invalid-embedding-vectors-re-i","errorCode":null,"errorMessage":"RAG index contains invalid embedding vectors. Re-index the knowledge base with the current embedding provider/model before querying it again. Details: {exc}","messagePattern":"RAG index contains invalid embedding vectors\\. Re-index the knowledge base with the current embedding provider/model before querying it again\\. Details: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"critical","filePath":"deeptutor/services/rag/pipelines/llamaindex/storage.py","lineNumber":190,"sourceCode":"            with open(path, encoding=\"utf-8\") as handle:\n                payload = json.load(handle)\n        except Exception:\n            continue\n        embedding_dict = _embedding_dict_from_payload(payload)\n        if isinstance(embedding_dict, dict):\n            yield path.name, embedding_dict\n\n\ndef _validate_persisted_embeddings(index: Any, storage_dir: Path | None = None) -> None:\n    \"\"\"Fail early when a persisted vector store contains unusable vectors.\"\"\"\n    try:\n        for label, embedding_dict in _iter_index_embedding_dicts(index):\n            _validate_embedding_dict(embedding_dict, label=label)\n        if storage_dir is not None:\n            for label, embedding_dict in _iter_file_embedding_dicts(storage_dir):\n                _validate_embedding_dict(embedding_dict, label=label)\n    except ValueError as exc:\n        raise ValueError(\n            \"RAG index contains invalid embedding vectors. Re-index the \"\n            \"knowledge base with the current embedding provider/model before \"\n            f\"querying it again. Details: {exc}\"\n        ) from exc\n\n\ndef validate_storage_embeddings(storage_dir: Path) -> None:\n    \"\"\"Validate persisted vector-store files without running a retrieval.\"\"\"\n    _validate_persisted_embeddings(None, storage_dir)\n\n\n# Loaded indexes are cached per storage dir so repeated queries never re-read or\n# re-validate the (potentially large) persisted store. Entries are keyed by a\n# freshness token derived from the store files' mtimes, so a re-index or\n# incremental insert naturally invalidates the stale entry.\n@dataclass\nclass _CachedIndex:\n    index: Any","sourceCodeStart":172,"sourceCodeEnd":208,"githubUrl":"https://github.com/HKUDS/DeepTutor/blob/3e82f130422a813cdd73c10b21a44e9325f5821a/deeptutor/services/rag/pipelines/llamaindex/storage.py#L172-L208","documentation":"Thrown when persisted RAG index embeddings fail validation — vectors are NaN/Inf, zero-length, ragged dimensions, or mismatched against the current embedding model. Because stored vectors are incompatible, the only safe recovery is re-indexing with the current embedding provider.","triggerScenarios":"Calling insert_documents(), validate_storage_embeddings(), or loading a persisted index whose vector store was built with a different embedding model/dimension, or whose on-disk JSON/docstore vectors are corrupted (NaN from a bad batch).","commonSituations":"Switching embedding models (e.g., text-embedding-3-small → bge-large) without re-creating the knowledge base, partially-written storage after a crashed indexing run, or a provider returning NaN embeddings under numeric overflow.","solutions":["Re-index the knowledge base with the current embedding provider: delete/recreate the KB and re-run add_documents.","Confirm the embedding model configured now matches the one used when the KB was created; if you intentionally switched models, re-indexing is required.","Run validate_storage_embeddings() after indexing to catch NaN/ragged vectors early; if the provider emits NaN, switch embedding backend.","If storage corruption is suspected (crash mid-write), restore from backup or wipe data/user storage for that KB and rebuild."],"exampleFix":"# before\nindex = load_index(storage_dir=kb_path)  # ValueError: invalid embedding vectors\n\n# after\nkb.delete()\nkb = pipeline.create_kb(\"my-kb\")\nkb.add_documents(documents)  # re-embed with current provider\nindex = load_index(storage_dir=kb.path)","handlingStrategy":"validation","validationCode":"from deeptutor.services.rag.pipelines.llamaindex.storage import validate_storage_embeddings\nvalidate_storage_embeddings(storage_dir)  # run before querying a persisted KB","typeGuard":null,"tryCatchPattern":"try:\n    index = load_index(storage_dir=kb_path)\nexcept ValueError as e:\n    if \"invalid embedding vectors\" in str(e):\n        rebuild_kb(kb_path)  # wipe + re-index\n    else:\n        raise","preventionTips":["Never switch embedding models without re-indexing existing KBs.","Pin the embedding model per KB and record it in KB metadata.","Validate persisted embeddings right after indexing completes.","Back up KB storage before provider/model changes."],"tags":["rag","embeddings","index-corruption","vector-store","llamaindex"],"backgroundTag":"embedding-dimension-mismatch","analyzedSha":"3e82f130422a813cdd73c10b21a44e9325f5821a","analyzedAt":"2026-08-27T06:57:25.364Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}