{"record":{"id":"9f02e0f058a727f5","repo":"run-llama/llama_index","slug":"invalid-embedding-name-name","errorCode":null,"errorMessage":"Invalid Embedding name: {name}","messagePattern":"Invalid Embedding name: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/embeddings/loading.py","lineNumber":47,"sourceCode":"        HuggingFaceInferenceAPIEmbedding,\n    )  # pants: no-infer-dep\n\n    RECOGNIZED_EMBEDDINGS[HuggingFaceInferenceAPIEmbedding.class_name()] = (\n        HuggingFaceInferenceAPIEmbedding\n    )\nexcept ImportError:\n    pass\n\n\ndef load_embed_model(data: dict) -> BaseEmbedding:\n    \"\"\"Load Embedding by name.\"\"\"\n    if isinstance(data, BaseEmbedding):\n        return data\n    name = data.get(\"class_name\")\n    if name is None:\n        raise ValueError(\"Embedding loading requires a class_name\")\n    if name not in RECOGNIZED_EMBEDDINGS:\n        raise ValueError(f\"Invalid Embedding name: {name}\")\n\n    return RECOGNIZED_EMBEDDINGS[name].from_dict(data)\n","sourceCodeStart":29,"sourceCodeEnd":50,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/embeddings/loading.py#L29-L50","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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","Install the integration package that provides the class (e.g. pip install llama-index-embeddings-huggingface) so it gets registered","For custom embedding classes, instantiate them directly instead of load_embed_model, or register them in RECOGNIZED_EMBEDDINGS yourself"],"exampleFix":"// before\nload_embed_model({\"class_name\": \"HuggingFaceEmbedding\", ...})\n# ValueError: Invalid Embedding name (package not installed -> not registered)\n\n// after\n# pip install llama-index-embeddings-huggingface\nfrom llama_index.core.embeddings.loading import RECOGNIZED_EMBEDDINGS\nassert \"HuggingFaceEmbedding\" in RECOGNIZED_EMBEDDINGS\nembed_model = load_embed_model({\"class_name\": \"HuggingFaceEmbedding\", ...})","handlingStrategy":"validation","validationCode":"from llama_index.core.embeddings.loading import RECOGNIZED_EMBEDDINGS\nname = data.get(\"class_name\")\nif name not in RECOGNIZED_EMBEDDINGS:\n    raise ValueError(f\"unknown class_name {name!r}; valid: {sorted(RECOGNIZED_EMBEDDINGS)}\")","typeGuard":"from llama_index.core.embeddings.loading import RECOGNIZED_EMBEDDINGS\n\ndef is_recognized_embedding(data: dict) -> bool:\n    return data.get(\"class_name\") in RECOGNIZED_EMBEDDINGS","tryCatchPattern":"try:\n    embed_model = load_embed_model(data)\nexcept ValueError as e:\n    if \"Invalid Embedding name\" in str(e):\n        raise RuntimeError(\n            f\"install the integration for {data.get('class_name')} \"\n            f\"or use one of {sorted(RECOGNIZED_EMBEDDINGS)}\"\n        ) from e\n    raise","preventionTips":["Serialize and deserialize in environments with the same integration packages installed","Validate class_name against RECOGNIZED_EMBEDDINGS at config-load time","Instantiate custom embedding classes directly; do not route them through load_embed_model"],"tags":["embeddings","serialization","dependencies","registry"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}