run-llama/llama_index · error · ValueError

Invalid Embedding name: {name}

Error message

Invalid Embedding name: {name}

What it means

load_embed_model(data) found a class_name string but it is not a key in RECOGNIZED_EMBEDDINGS, the registry of importable embedding classes. Entries are added only when their integration package imports successfully, so an unknown name means either a typo or a class whose package is not installed/importable in this environment.

Source

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

        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. Print the valid names — from llama_index.core.embeddings.loading import RECOGNIZED_EMBEDDINGS; print(RECOGNIZED_EMBEDDINGS.keys()) — and fix class_name to one of them
2. Install the integration package that provides the class (e.g. pip install llama-index-embeddings-huggingface) so it gets registered
3. For custom embedding classes, instantiate them directly instead of load_embed_model, or register them in RECOGNIZED_EMBEDDINGS yourself

Example fix

// before
load_embed_model({"class_name": "HuggingFaceEmbedding", ...})
# ValueError: Invalid Embedding name (package not installed -> not registered)

// after
# pip install llama-index-embeddings-huggingface
from llama_index.core.embeddings.loading import RECOGNIZED_EMBEDDINGS
assert "HuggingFaceEmbedding" in RECOGNIZED_EMBEDDINGS
embed_model = load_embed_model({"class_name": "HuggingFaceEmbedding", ...})

from llama_index.core.embeddings.loading import RECOGNIZED_EMBEDDINGS
name = data.get("class_name")
if name not in RECOGNIZED_EMBEDDINGS:
    raise ValueError(f"unknown class_name {name!r}; valid: {sorted(RECOGNIZED_EMBEDDINGS)}")

from llama_index.core.embeddings.loading import RECOGNIZED_EMBEDDINGS

def is_recognized_embedding(data: dict) -> bool:
    return data.get("class_name") in RECOGNIZED_EMBEDDINGS

try:
    embed_model = load_embed_model(data)
except ValueError as e:
    if "Invalid Embedding name" in str(e):
        raise RuntimeError(
            f"install the integration for {data.get('class_name')} "
            f"or use one of {sorted(RECOGNIZED_EMBEDDINGS)}"
        ) from e
    raise

When it happens

Trigger: load_embed_model({'class_name': 'openai', ...}) or a renamed/moved class; class_name of an embedding whose integration (e.g. llama-index-embeddings-huggingface) is missing, so its RECOGNIZED_EMBEDDINGS registration was skipped due to ImportError.

Common situations: Serializing an embedding in one environment and deserializing in another without the integration installed; class renamed across llama-index versions (old persisted dicts); custom embedding subclasses that were never registered.

Related errors

• Embedding loading requires a class_name
• `llama-index-embeddings-openai` package not found, please ru
• `llama-index-embeddings-clip` package not found, please run
• `llama-index-embeddings-huggingface` package not found, plea
• `llama-index-embeddings-langchain` package not found, please

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