HKUDS/DeepTutor · critical · ValueError

RAG index contains invalid embedding vectors. Re-index the k

Error message

RAG index contains invalid embedding vectors. Re-index the knowledge base with the current embedding provider/model before querying it again. Details: {exc}

What it means

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.

Source

Thrown at deeptutor/services/rag/pipelines/llamaindex/storage.py:190

            with open(path, encoding="utf-8") as handle:
                payload = json.load(handle)
        except Exception:
            continue
        embedding_dict = _embedding_dict_from_payload(payload)
        if isinstance(embedding_dict, dict):
            yield path.name, embedding_dict


def _validate_persisted_embeddings(index: Any, storage_dir: Path | None = None) -> None:
    """Fail early when a persisted vector store contains unusable vectors."""
    try:
        for label, embedding_dict in _iter_index_embedding_dicts(index):
            _validate_embedding_dict(embedding_dict, label=label)
        if storage_dir is not None:
            for label, embedding_dict in _iter_file_embedding_dicts(storage_dir):
                _validate_embedding_dict(embedding_dict, label=label)
    except ValueError as exc:
        raise ValueError(
            "RAG index contains invalid embedding vectors. Re-index the "
            "knowledge base with the current embedding provider/model before "
            f"querying it again. Details: {exc}"
        ) from exc


def validate_storage_embeddings(storage_dir: Path) -> None:
    """Validate persisted vector-store files without running a retrieval."""
    _validate_persisted_embeddings(None, storage_dir)


# Loaded indexes are cached per storage dir so repeated queries never re-read or
# re-validate the (potentially large) persisted store. Entries are keyed by a
# freshness token derived from the store files' mtimes, so a re-index or
# incremental insert naturally invalidates the stale entry.
@dataclass
class _CachedIndex:
    index: Any

View on GitHub (pinned to 3e82f13042)

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.

Example fix

# before
index = load_index(storage_dir=kb_path)  # ValueError: invalid embedding vectors

# after
kb.delete()
kb = pipeline.create_kb("my-kb")
kb.add_documents(documents)  # re-embed with current provider
index = load_index(storage_dir=kb.path)

Defensive patterns

Strategy: validation

Validate before calling

from deeptutor.services.rag.pipelines.llamaindex.storage import validate_storage_embeddings
validate_storage_embeddings(storage_dir)  # run before querying a persisted KB

Try / catch

try:
    index = load_index(storage_dir=kb_path)
except ValueError as e:
    if "invalid embedding vectors" in str(e):
        rebuild_kb(kb_path)  # wipe + re-index
    else:
        raise

Prevention

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.

When it happens

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

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

Related errors

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