{"record":{"id":"3b8b46316e391b2b","repo":"run-llama/llama_index","slug":"llm-loading-requires-a-class-name","errorCode":null,"errorMessage":"LLM loading requires a class_name","messagePattern":"LLM loading requires a class_name","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/llms/loading.py","lineNumber":41,"sourceCode":"    pass\n\ntry:\n    from llama_index.llms.huggingface_api import (\n        HuggingFaceInferenceAPI,\n    )  # pants: no-infer-dep\n\n    RECOGNIZED_LLMS[HuggingFaceInferenceAPI.class_name()] = HuggingFaceInferenceAPI\nexcept ImportError:\n    pass\n\n\ndef load_llm(data: dict) -> LLM:\n    \"\"\"Load LLM by name.\"\"\"\n    if isinstance(data, LLM):\n        return data\n    llm_name = data.get(\"class_name\")\n    if llm_name is None:\n        raise ValueError(\"LLM loading requires a class_name\")\n\n    if llm_name not in RECOGNIZED_LLMS:\n        raise ValueError(f\"Invalid LLM name: {llm_name}\")\n\n    return RECOGNIZED_LLMS[llm_name].from_dict(data)\n","sourceCodeStart":23,"sourceCodeEnd":47,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/llms/loading.py#L23-L47","documentation":"load_llm() deserializes an LLM from a dict and requires a 'class_name' key to look up the concrete class in RECOGNIZED_LLMS. If the dict has no class_name (or it is None), the registry lookup is impossible, so a ValueError is raised before any construction is attempted.","triggerScenarios":"Calling llama_index.core.llms.loading.load_llm(data) with a dict that lacks the 'class_name' key — e.g. a hand-built dict, a JSON export that stripped the key, or a dict produced by a different serialization format.","commonSituations":"Persisting LLM config to JSON and reloading it after a format change; passing generic kwargs (like {'model': 'gpt-4'}) instead of a full serialized LLM; loading configs written by an older/newer llama-index version whose to_dict schema differs.","solutions":["Ensure the dict came from llm.to_dict() / llm.to_json() — those always embed class_name.","Manually add the key: data['class_name'] = 'OpenAI' (must match a registered class name).","If you only need a specific LLM, construct it directly (e.g. OpenAI(model=...)) instead of round-tripping through load_llm."],"exampleFix":"# before\nllm = load_llm({\"model\": \"gpt-4o\"})\n# after\nllm = load_llm({\"class_name\": \"OpenAI\", \"model\": \"gpt-4o\"})\n# or simply\nllm = OpenAI(model=\"gpt-4o\")","handlingStrategy":"validation","validationCode":"def is_loadable_llm_dict(data: dict) -> bool:\n    return isinstance(data, dict) and isinstance(data.get(\"class_name\"), str)","typeGuard":"def is_llm_payload(data) -> bool:\n    return hasattr(data, \"class_name\") or (isinstance(data, dict) and \"class_name\" in data)","tryCatchPattern":"try:\n    llm = load_llm(data)\nexcept ValueError as e:\n    if \"class_name\" in str(e):\n        raise ValueError(f\"Refusing to load LLM config without class_name: {data!r}\") from e\n    raise","preventionTips":["Always serialize LLMs via llm.to_dict()/to_json() so class_name is embedded.","Validate 'class_name' in data before calling load_llm.","Pin llama-index versions across save/load environments so dict schemas match."],"tags":["llama-index","serialization","deserialization","config"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}