mem0ai/mem0 · error · ValueError

Invalid docstore format: expected tuple of (docstore, index_

Error message

Invalid docstore format: expected tuple of (docstore, index_to_id)

What it means

Raised by _validate_docstore_structure() when loading a persisted FAISS docstore whose on-disk representation is not a 2-tuple of (docstore, index_to_id). Mem0 serializes its FAISS side-data as this tuple, so anything else means the file is corrupt or was written by different code. It is a hard ValueError raised during FAISS.__init__/load.

Source

Thrown at mem0/vector_stores/faiss.py:94

    with open(file_path, "rb") as f:
        return SafeUnpickler(f).load()


def _validate_docstore_structure(data: Any) -> tuple:
    """
    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():

View on GitHub (pinned to 001c235229)

Solutions

Delete or move the corrupted docstore file (path/faiss.docstore or faiss.docstore.json) and let mem0 rebuild the collection from scratch
Regenerate the persisted store from the source memories (re-run adds) if the data is valuable
Pin the mem0 version that originally wrote the file, load and re-export the data, then upgrade
Verify the JSON file parses and contains both docstore and index_to_id keys before constructing FAISS

Example fix

# before
vs = FAISS(config)  # ValueError: Invalid docstore format: expected tuple...

# after
import os, json
p = os.path.join(config.path, 'faiss.docstore.json')
if os.path.exists(p):
    data = json.load(open(p))
    assert isinstance(data, (list, tuple)) and len(data) == 2, 'corrupt docstore'
vs = FAISS(config)

Defensive patterns

Strategy: validation

Validate before calling

import json, os

def docstore_tuple_ok(path):
    p = os.path.join(path, 'faiss.docstore.json')
    if not os.path.exists(p):
        return False
    data = json.load(open(p))
    return isinstance(data, (list, tuple)) and len(data) == 2

Type guard

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

Try / catch

try:
    vs = FAISS(config)
except ValueError as e:
    if 'Invalid docstore format' in str(e):
        # corrupt/incompatible store: quarantine and rebuild
        raise

Prevention

Never hand-edit persisted faiss.docstore.json files
Back up the whole collection directory (index + docstore) together
Test loads after every mem0 version upgrade before writing new data

When it happens

Trigger: Calling FAISS(...) with a path whose .pkl (legacy) or .json docstore file deserializes to something other than a 2-element tuple — e.g. a truncated file, a file written by an older mem0 version with a different schema, or a user-supplied pickle containing a random object.

Common situations: Upgrading mem0 across versions that changed the docstore serialization format; pointing collection_path at a directory with leftover files from another tool; partially written files after a crash during _save().

Related errors

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