run-llama/llama_index · error · ValueError

Invalid LLM name: {llm_name}

Error message

Invalid LLM name: {llm_name}

What it means

load_llm() found a class_name string but it is not a key in the RECOGNIZED_LLMS registry, which only contains core LLMs plus optional integrations (like HuggingFaceInferenceAPI) that registered themselves if their imports succeeded. The ValueError names the offending class so you can see exactly what string failed.

Source

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

    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. Check the exact registered name: from llama_index.core.llms.loading import RECOGNIZED_LLMS; print(RECOGNIZED_LLMS.keys()).
2. Install the missing integration package (e.g. pip install llama-index-llms-openai) so the class registers at import time.
3. For custom classes, import the class and assign RECOGNIZED_LLMS[MyLLM.class_name()] = MyLLM before load_llm.
4. Match casing exactly — registry keys are the class_name() strings, typically the class name.

Example fix

# before
llm = load_llm({"class_name": "openai", "model": "gpt-4o"})
# after
from llama_index.core.llms.loading import RECOGNIZED_LLMS
assert "OpenAI" in RECOGNIZED_LLMS  # verify exact spelling
llm = load_llm({"class_name": "OpenAI", "model": "gpt-4o"})

from llama_index.core.llms.loading import RECOGNIZED_LLMS

def is_recognized_llm_name(data: dict) -> bool:
    return data.get("class_name") in RECOGNIZED_LLMS

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 "Invalid LLM name" in str(e):
        raise ValueError(
            f"{data.get('class_name')!r} not registered. "
            f"Known: {sorted(RECOGNIZED_LLMS)}"
        ) from e
    raise

When it happens

Trigger: Calling load_llm(data) where data['class_name'] is misspelled (e.g. 'openai' vs 'OpenAI'), refers to a third-party LLM class whose integration package is not installed (so it never registered), or refers to a custom LLM subclass that was never registered via RECOGNIZED_LLMS.

Common situations: Loading configs across environments where integration packages differ; class renamed between llama-index versions; custom LLM subclasses serialized on one machine and deserialized on another without the class registered.

Related errors

• Invalid ChatStore name: {chat_store_name}
• First argument to Readability constructor should be a docume
• Command failed: {command} {result.stderr}
• Must provide either user_msg or chat_history
• Invalid Embedding name: {name}

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