run-llama/llama_index · error · ValueError

Embedding loading requires a class_name

Error message

Embedding loading requires a class_name

What it means

load_embed_model(data) reconstructs a BaseEmbedding from a dict serialized via to_dict(); it dispatches on the 'class_name' key to find the right class in RECOGNIZED_EMBEDDINGS. A dict without class_name (or with it spelled differently, e.g. 'class' or 'type') cannot be deserialized and is rejected immediately.

Source

Thrown at llama-index-core/llama_index/core/embeddings/loading.py:45

try:
    from llama_index.embeddings.huggingface_api import (
        HuggingFaceInferenceAPIEmbedding,
    )  # pants: no-infer-dep

    RECOGNIZED_EMBEDDINGS[HuggingFaceInferenceAPIEmbedding.class_name()] = (
        HuggingFaceInferenceAPIEmbedding
    )
except ImportError:
    pass


def load_embed_model(data: dict) -> BaseEmbedding:
    """Load Embedding by name."""
    if isinstance(data, BaseEmbedding):
        return data
    name = data.get("class_name")
    if name is None:
        raise ValueError("Embedding loading requires a class_name")
    if name not in RECOGNIZED_EMBEDDINGS:
        raise ValueError(f"Invalid Embedding name: {name}")

    return RECOGNIZED_EMBEDDINGS[name].from_dict(data)

View on GitHub (pinned to afd0fef371)

Solutions

1. Serialize with the library's own method — embed_model.to_dict() always includes class_name — and pass that dict to load_embed_model
2. Add the key manually: data['class_name'] = 'OpenAIEmbedding' (must be a name present in llama_index.core.embeddings.loading.RECOGNIZED_EMBEDDINGS)
3. If you only have model settings, construct the embedding class directly instead of going through load_embed_model

Example fix

// before
load_embed_model({"model_name": "text-embedding-ada-002"})  # ValueError

// after
embed_model = OpenAIEmbedding()
saved = embed_model.to_dict()          # includes class_name
restored = load_embed_model(saved)     # ok

if not isinstance(data, dict) or "class_name" not in data:
    raise ValueError("embedding dict must contain 'class_name'")

def is_loadable_embedding_dict(data) -> bool:
    return isinstance(data, dict) and isinstance(data.get("class_name"), str)

try:
    embed_model = load_embed_model(data)
except ValueError as e:
    if "class_name" in str(e):
        data = {**data, "class_name": "OpenAIEmbedding"}
        embed_model = load_embed_model(data)
    else:
        raise

When it happens

Trigger: Calling load_embed_model({'model_name': 'BAAI/bge-small'}) (missing key); loading embeddings from JSON where the key was renamed or the dict was hand-written; passing a partially-constructed dict from a different serialization format.

Common situations: Persisting embed model config yourself and dropping the class_name field; round-tripping dicts through code that whitelists/filter keys; version changes that altered serialization keys.

Related errors

• Invalid Embedding name: {name}
• Objs is not pickleable
• ChatStore loading requires a class_name
• Invalid ChatStore name: {chat_store_name}
• First argument to Readability constructor should be a docume

AI-assisted analysis of run-llama/llama_index@afd0fef371 (2026-08-15). Data as JSON: /api/errors/e2730e871e2bb5d3. Report an issue: GitHub.