run-llama/llama_index · error · ValueError

LLM loading requires a class_name

Error message

LLM loading requires a class_name

What it means

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.

Source

Thrown at llama-index-core/llama_index/core/llms/loading.py:41

    pass

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

    RECOGNIZED_LLMS[HuggingFaceInferenceAPI.class_name()] = HuggingFaceInferenceAPI
except ImportError:
    pass


def load_llm(data: dict) -> LLM:
    """Load LLM by name."""
    if isinstance(data, LLM):
        return data
    llm_name = data.get("class_name")
    if llm_name is None:
        raise ValueError("LLM loading requires a class_name")

    if llm_name not in RECOGNIZED_LLMS:
        raise ValueError(f"Invalid LLM name: {llm_name}")

    return RECOGNIZED_LLMS[llm_name].from_dict(data)

View on GitHub (pinned to afd0fef371)

Solutions

1. Ensure the dict came from llm.to_dict() / llm.to_json() — those always embed class_name.
2. Manually add the key: data['class_name'] = 'OpenAI' (must match a registered class name).
3. If you only need a specific LLM, construct it directly (e.g. OpenAI(model=...)) instead of round-tripping through load_llm.

Example fix

# before
llm = load_llm({"model": "gpt-4o"})
# after
llm = load_llm({"class_name": "OpenAI", "model": "gpt-4o"})
# or simply
llm = OpenAI(model="gpt-4o")

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

def is_llm_payload(data) -> bool:
    return hasattr(data, "class_name") or (isinstance(data, dict) and "class_name" in data)

try:
    llm = load_llm(data)
except ValueError as e:
    if "class_name" in str(e):
        raise ValueError(f"Refusing to load LLM config without class_name: {data!r}") from e
    raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Must specify `class_name` in reader data.
• First argument to Readability constructor should be a docume
• Command failed: {command} {result.stderr}
• Git command failed: {result.stderr}
• Must provide either user_msg or chat_history

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