{"record":{"id":"e2730e871e2bb5d3","repo":"run-llama/llama_index","slug":"embedding-loading-requires-a-class-name","errorCode":null,"errorMessage":"Embedding loading requires a class_name","messagePattern":"Embedding loading requires a class_name","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/embeddings/loading.py","lineNumber":45,"sourceCode":"try:\n    from llama_index.embeddings.huggingface_api import (\n        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":27,"sourceCodeEnd":50,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/embeddings/loading.py#L27-L50","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Serialize with the library's own method — embed_model.to_dict() always includes class_name — and pass that dict to load_embed_model","Add the key manually: data['class_name'] = 'OpenAIEmbedding' (must be a name present in llama_index.core.embeddings.loading.RECOGNIZED_EMBEDDINGS)","If you only have model settings, construct the embedding class directly instead of going through load_embed_model"],"exampleFix":"// before\nload_embed_model({\"model_name\": \"text-embedding-ada-002\"})  # ValueError\n\n// after\nembed_model = OpenAIEmbedding()\nsaved = embed_model.to_dict()          # includes class_name\nrestored = load_embed_model(saved)     # ok","handlingStrategy":"validation","validationCode":"if not isinstance(data, dict) or \"class_name\" not in data:\n    raise ValueError(\"embedding dict must contain 'class_name'\")","typeGuard":"def is_loadable_embedding_dict(data) -> bool:\n    return isinstance(data, dict) and isinstance(data.get(\"class_name\"), str)","tryCatchPattern":"try:\n    embed_model = load_embed_model(data)\nexcept ValueError as e:\n    if \"class_name\" in str(e):\n        data = {**data, \"class_name\": \"OpenAIEmbedding\"}\n        embed_model = load_embed_model(data)\n    else:\n        raise","preventionTips":["Always serialize with embed_model.to_dict() rather than hand-building dicts","Pin schema: assert 'class_name' in d before persisting","Round-trip test (to_dict -> load_embed_model) whenever you change serialization code"],"tags":["embeddings","serialization","persistence"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}