{"record":{"id":"b567e39e7d8817cc","repo":"mem0ai/mem0","slug":"invalid-docstore-format-expected-tuple-of-docsto","errorCode":null,"errorMessage":"Invalid docstore format: expected tuple of (docstore, index_to_id)","messagePattern":"Invalid docstore format: expected tuple of \\(docstore, index_to_id\\)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"mem0/vector_stores/faiss.py","lineNumber":94,"sourceCode":"    with open(file_path, \"rb\") as f:\n        return SafeUnpickler(f).load()\n\n\ndef _validate_docstore_structure(data: Any) -> tuple:\n    \"\"\"\n    Validate that loaded data has the expected structure.\n\n    Args:\n        data: The loaded data to validate.\n\n    Returns:\n        Tuple of (docstore, index_to_id) if valid.\n\n    Raises:\n        ValueError: If the data structure is invalid.\n    \"\"\"\n    if not isinstance(data, tuple) or len(data) != 2:\n        raise ValueError(\"Invalid docstore format: expected tuple of (docstore, index_to_id)\")\n\n    docstore, index_to_id = data\n\n    if not isinstance(docstore, dict):\n        raise ValueError(\"Invalid docstore format: docstore must be a dict\")\n\n    if not isinstance(index_to_id, dict):\n        raise ValueError(\"Invalid docstore format: index_to_id must be a dict\")\n\n    # Validate docstore entries\n    for key, value in docstore.items():\n        if not isinstance(key, str):\n            raise ValueError(f\"Invalid docstore key type: {type(key)}, expected str\")\n        if not isinstance(value, dict):\n            raise ValueError(f\"Invalid docstore value type: {type(value)}, expected dict\")\n\n    # Validate index_to_id entries\n    for key, value in index_to_id.items():","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/mem0ai/mem0/blob/001c235229be8795e3834520467bd0d661ed8f34/mem0/vector_stores/faiss.py#L76-L112","documentation":"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.","triggerScenarios":"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.","commonSituations":"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().","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"],"exampleFix":"# before\nvs = FAISS(config)  # ValueError: Invalid docstore format: expected tuple...\n\n# after\nimport os, json\np = os.path.join(config.path, 'faiss.docstore.json')\nif os.path.exists(p):\n    data = json.load(open(p))\n    assert isinstance(data, (list, tuple)) and len(data) == 2, 'corrupt docstore'\nvs = FAISS(config)","handlingStrategy":"validation","validationCode":"import json, os\n\ndef docstore_tuple_ok(path):\n    p = os.path.join(path, 'faiss.docstore.json')\n    if not os.path.exists(p):\n        return False\n    data = json.load(open(p))\n    return isinstance(data, (list, tuple)) and len(data) == 2","typeGuard":"def is_valid_docstore_tuple(data) -> bool:\n    return (\n        isinstance(data, (tuple, list)) and len(data) == 2\n        and isinstance(data[0], dict)\n        and isinstance(data[1], dict)\n    )","tryCatchPattern":"try:\n    vs = FAISS(config)\nexcept ValueError as e:\n    if 'Invalid docstore format' in str(e):\n        # corrupt/incompatible store: quarantine and rebuild\n        raise","preventionTips":["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"],"tags":["faiss","vector-store","persistence","data-corruption"],"backgroundTag":null,"analyzedSha":"001c235229be8795e3834520467bd0d661ed8f34","analyzedAt":"2026-08-15T01:55:42.685Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}