run-llama/llama_index · error · ValueError

Extractor loading requires a class_name

Error message

Extractor loading requires a class_name

What it means

Raised by load_extractor() when the input dict has no 'class_name' key. load_extractor reconstructs an extractor from its serialized dict form, and class_name is the discriminator used to pick the right from_dict constructor; it also short-circuits if the input is already a BaseExtractor instance.

Source

Thrown at llama-index-core/llama_index/core/extractors/loading.py:18

from llama_index.core.extractors.metadata_extractors import (
    BaseExtractor,
    KeywordExtractor,
    QuestionsAnsweredExtractor,
    SummaryExtractor,
    TitleExtractor,
)


def load_extractor(
    data: dict,
) -> BaseExtractor:
    if isinstance(data, BaseExtractor):
        return data

    extractor_name = data.get("class_name")
    if extractor_name is None:
        raise ValueError("Extractor loading requires a class_name")

    if extractor_name == SummaryExtractor.class_name():
        return SummaryExtractor.from_dict(data)
    elif extractor_name == QuestionsAnsweredExtractor.class_name():
        return QuestionsAnsweredExtractor.from_dict(data)
    elif extractor_name == TitleExtractor.class_name():
        return TitleExtractor.from_dict(data)
    elif extractor_name == KeywordExtractor.class_name():
        return KeywordExtractor.from_dict(data)
    else:
        raise ValueError(f"Unknown extractor name: {extractor_name}")

View on GitHub (pinned to afd0fef371)

Solutions

1. Include the discriminator: data['class_name'] = 'KeywordExtractor' (or the appropriate extractor name) before calling load_extractor.
2. Serialize extractors with their full to_dict()/model_dump() output so class_name round-trips automatically.
3. If the dict is really just kwargs, construct the extractor class directly instead of using load_extractor.

Example fix

# before
extractor = load_extractor({"keywords": 3})

# after
extractor = load_extractor({"class_name": "KeywordExtractor", "keywords": 3})

if isinstance(data, dict) and "class_name" not in data:
    raise ValueError("Extractor config dict must include 'class_name'")
extractor = load_extractor(data)

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

When it happens

Trigger: Calling load_extractor({'keywords': 3}) or load_extractor({}) on a hand-built or trimmed dict — e.g. one loaded from JSON that was serialized without the class discriminator, or a config section missing the type key.

Common situations: Persisting extractor configs with .model_dump(exclude=...) or json.dumps of a subset of fields; deserializing old config files; passing a list of kwargs dicts intended for direct constructor calls into load_extractor by mistake.

Related errors

• Invalid metric name: {metric}
• Cannot specify both similarity_fn and similarity_mode
• Unknown oversized document strategy: {strategy}
• Unknown extractor name: {extractor_name}
• num_nodes must be >= 1

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