run-llama/llama_index · error · ValueError

ChatStore loading requires a class_name

Error message

ChatStore loading requires a class_name

What it means

load_chat_store(data) reconstructs a chat store from a dict produced by its to_dict(). It requires a 'class_name' key to select the class; the dict is empty, missing the key, or malformed. Only classes registered in RECOGNIZED_CHAT_STORES (just SimpleChatStore) can be loaded.

Source

Thrown at llama-index-core/llama_index/core/storage/chat_store/loading.py:13

from llama_index.core.storage.chat_store.base import BaseChatStore
from llama_index.core.storage.chat_store.simple_chat_store import SimpleChatStore

RECOGNIZED_CHAT_STORES = {
    SimpleChatStore.class_name(): SimpleChatStore,
}


def load_chat_store(data: dict) -> BaseChatStore:
    """Load a chat store from a dict."""
    chat_store_name = data.get("class_name")
    if chat_store_name is None:
        raise ValueError("ChatStore loading requires a class_name")

    if chat_store_name not in RECOGNIZED_CHAT_STORES:
        raise ValueError(f"Invalid ChatStore name: {chat_store_name}")

    return RECOGNIZED_CHAT_STORES[chat_store_name].from_dict(data)

View on GitHub (pinned to afd0fef371)

Solutions

1. Ensure the dict came from SimpleChatStore.to_dict() and still contains its 'class_name' entry.
2. If loading arbitrary dicts, add the key explicitly: data['class_name'] = SimpleChatStore.class_name() before calling load_chat_store.
3. For other chat store types (RedisChatStore, DatabaseChatStore), instantiate them directly with their own connection args instead of load_chat_store.
4. Validate persisted payloads before reload (see validation below).

Example fix

# before
store = load_chat_store({'messages': saved})  # missing class_name

# after
from llama_index.core.storage.chat_store.simple_chat_store import SimpleChatStore
store = load_chat_store({'class_name': SimpleChatStore.class_name(), 'messages': saved})

from llama_index.core.storage.chat_store.loading import load_chat_store

def safe_load_chat_store(data: dict):
    if not isinstance(data, dict) or 'class_name' not in data:
        raise ValueError('Chat store payload must be a dict with a class_name key')
    return load_chat_store(data)

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

try:
    store = load_chat_store(data)
except ValueError as e:
    if 'class_name' in str(e):
        data = {**data, 'class_name': 'SimpleChatStore'}
        store = load_chat_store(data)
    else:
        raise

When it happens

Trigger: Calling load_chat_store({}) or load_chat_store({'messages': ...}) on a dict without 'class_name' -- e.g. hand-built config, a JSON file edited manually, or a payload from chat_store.to_dict() of an unregistered store type.

Common situations: Persisting chat history to JSON and reloading it; deserializing a payload written by a different chat store implementation (Redis/Postgres table export) or by a newer/older version whose dict schema differs.

Related errors

• Invalid ChatStore name: {chat_store_name}
• Failed to serialize additional_kwargs value: {value}
• First argument to Readability constructor should be a docume
• Command failed: {command} {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/d7b5a7e88fcbc399. Report an issue: GitHub.