mem0ai/mem0 · error · ValueError

Invalid docstore format: docstore must be a dict

Error message

Invalid docstore format: docstore must be a dict

What it means

Raised by _validate_docstore_structure() when the first element of the loaded (docstore, index_to_id) tuple is not a dict. The docstore maps memory-id -> payload dict; a non-dict means the pickle/JSON was tampered with or written by incompatible code. Raised during FAISS load as a ValueError.

Source

Thrown at mem0/vector_stores/faiss.py:99

    """
    Validate that loaded data has the expected structure.

    Args:
        data: The loaded data to validate.

    Returns:
        Tuple of (docstore, index_to_id) if valid.

    Raises:
        ValueError: If the data structure is invalid.
    """
    if not isinstance(data, tuple) or len(data) != 2:
        raise ValueError("Invalid docstore format: expected tuple of (docstore, index_to_id)")

    docstore, index_to_id = data

    if not isinstance(docstore, dict):
        raise ValueError("Invalid docstore format: docstore must be a dict")

    if not isinstance(index_to_id, dict):
        raise ValueError("Invalid docstore format: index_to_id must be a dict")

    # Validate docstore entries
    for key, value in docstore.items():
        if not isinstance(key, str):
            raise ValueError(f"Invalid docstore key type: {type(key)}, expected str")
        if not isinstance(value, dict):
            raise ValueError(f"Invalid docstore value type: {type(value)}, expected dict")

    # Validate index_to_id entries
    for key, value in index_to_id.items():
        if not isinstance(key, int):
            raise ValueError(f"Invalid index_to_id key type: {type(key)}, expected int")
        if not isinstance(value, str):
            raise ValueError(f"Invalid index_to_id value type: {type(value)}, expected str")

View on GitHub (pinned to 001c235229)

Solutions

Convert the foreign docstore to a plain dict before importing (dict(docstore) with str keys and dict values)
Delete the incompatible file and rebuild via mem0 adds
Write a one-off migration script that reads the old format and emits mem0's [docstore_dict, index_to_id_dict] JSON

Example fix

# before
# file saved by langchain FAISS.save_local -> docstore is Docstore, not dict
vs = FAISS(config)  # ValueError: docstore must be a dict

# after
# migration: dump as plain dict in mem0's expected shape
import json
json.dump([dict(docstore), index_to_id], open('faiss.docstore.json', 'w'))

Defensive patterns

Strategy: type-guard

Validate before calling

import json
data = json.load(open(p))
assert isinstance(data[0], dict), 'docstore must be a plain dict — convert Docstore objects first'

Type guard

def is_plain_dict_docstore(data) -> bool:
    return isinstance(data, (tuple, list)) and len(data) == 2 and isinstance(data[0], dict)

Prevention

When importing langchain FAISS stores, convert Docstore to dict(docstore) explicitly
Keep migration scripts that emit mem0's exact [dict, dict] shape

When it happens

Trigger: Loading a docstore tuple where data[0] is a list, string, or LangChain Docstore object instead of a plain dict — typically a legacy file produced by langchain_community FAISS serialization rather than mem0's own.

Common situations: Migrating a FAISS index saved via langchain's FAISS.save_local (whose docstore is a Docstore instance) into mem0's FAISS vector store; hand-editing the JSON file.

Related errors

AI-assisted analysis of mem0ai/mem0@001c235229 (2026-08-15). Data as JSON: /api/errors/8da3a1e214c4fbaa. Report an issue: GitHub.