mem0ai/mem0 · error · ValueError

Invalid docstore format: index_to_id must be a dict

Error message

Invalid docstore format: index_to_id must be a dict

What it means

Raised by _validate_docstore_structure() when the second element of the loaded tuple, index_to_id (faiss row -> memory id), is not a dict. This mapping is what ties FAISS row numbers to payload ids; a non-dict means incompatible or corrupt persistence. ValueError raised at load time.

Source

Thrown at mem0/vector_stores/faiss.py:102

    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")

    return docstore, index_to_id

View on GitHub (pinned to 001c235229)

Solutions

Inspect the persisted file and confirm element [1] is an object mapping integer-like keys to id strings
Restore from backup or delete the file and rebuild the index
Regenerate index_to_id by re-adding all memories in the same order

Defensive patterns

Strategy: type-guard

Validate before calling

import json
data = json.load(open(p))
assert isinstance(data[1], dict), 'index_to_id must be a dict of row -> id'

Type guard

def is_valid_index_to_id(x) -> bool:
    return isinstance(x, dict) and all(isinstance(k, int) and isinstance(v, str) for k, v in x.items())

Prevention

Always persist and migrate docstore and index_to_id as a pair
Automate format checks in CI for any data migration scripts

When it happens

Trigger: Loading a persisted docstore where data[1] is a list, None, or other non-dict — e.g. a JSON file edited to remove the second element, or a pickle from a different schema.

Common situations: Hand-migrating JSON docstores between environments; version drift between mem0 releases that changed the tuple layout; truncated files.

Related errors

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