run-llama/llama_index · error · ValueError

Must specify `class_name` in reader data.

Error message

Must specify `class_name` in reader data.

What it means

load_reader(data) deserializes a reader from a dict and requires a 'class_name' key to look up the class in the ALL_READERS registry. This ValueError is thrown when the dict has no 'class_name' entry (None). It is the standard entry point when restoring reader configs from JSON/persisted indexes or documents.

Source

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

from typing import Any, Dict, Type

from llama_index.core.readers.base import BasePydanticReader
from llama_index.core.readers.string_iterable import StringIterableReader

ALL_READERS: Dict[str, Type[BasePydanticReader]] = {
    StringIterableReader.class_name(): StringIterableReader,
}


def load_reader(data: Dict[str, Any]) -> BasePydanticReader:
    if isinstance(data, BasePydanticReader):
        return data

    class_name = data.get("class_name")

    if class_name is None:
        raise ValueError("Must specify `class_name` in reader data.")

    if class_name not in ALL_READERS:
        raise ValueError(f"Reader class name {class_name} not found.")

    # remove static attribute
    data.pop("is_remote", None)

    return ALL_READERS[class_name].from_dict(data)

View on GitHub (pinned to afd0fef371)

Solutions

1. Add 'class_name' to the payload before calling load_reader, e.g. data['class_name'] = 'StringIterableReader' (the name the reader's class_name() method returns).
2. If serializing yourself, use reader.to_dict() so class_name is included automatically, instead of building the dict by hand.
3. Upgrade/downgrade alignment: ensure the code that produced the dict and the code that reads it use the same llama-index version.

Example fix

# before
data = {"iterable": ["a", "b"]}  # no class_name
reader = load_reader(data)

# after
data = {"class_name": "StringIterableReader", "iterable": ["a", "b"]}
reader = load_reader(data)

def is_valid_reader_payload(data: dict) -> bool:
    return isinstance(data, dict) and "class_name" in data and data["class_name"]

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

try:
    reader = load_reader(data)
except ValueError as e:
    if "class_name" in str(e):
        raise ValueError(f"serialized reader payload missing class_name: {data}") from e
    raise

When it happens

Trigger: Calling load_reader({...}) on a hand-built dict that omits class_name; loading a document whose metadata/reader field was serialized by older code or a different library that did not include class_name; passing a partially constructed dict after popping or renaming keys.

Common situations: Round-tripping Document.reader through to_dict/from_dict across versions; storing reader configs in a database and dropping the class_name field; manual construction of reader payloads in pipelines.

Related errors

• LLM loading requires a class_name
• Could not infer node type for data: {node_dict!s}
• Reader class name {class_name} not found.
• First argument to Readability constructor should be a docume
• Command failed: {command} {result.stderr}

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