mem0ai/mem0 · error · FileNotFoundError

No docstore found at {docstore_path} or {json_docstore_path}

Error message

No docstore found at {docstore_path} or {json_docstore_path}

What it means

Raised during FAISS load when an index file exists but neither the legacy pickle docstore (faiss.docstore) nor the JSON docstore (faiss.docstore.json) is present at the expected path. Mem0 refuses to use a bare .index file because payloads would be lost. FileNotFoundError.

Source

Thrown at mem0/vector_stores/faiss.py:217

                logger.info(f"Loaded FAISS index from {index_path} with {self.index.ntotal} vectors (JSON format)")

            elif os.path.exists(docstore_path):
                # Load from legacy pickle using safe unpickler
                # This prevents arbitrary code execution from malicious pickle files
                logger.warning(
                    f"Loading legacy pickle docstore from {docstore_path}. "
                    f"Consider migrating to JSON format for better security."
                )
                data = _safe_pickle_load(docstore_path)
                self.docstore, self.index_to_id = _validate_docstore_structure(data)
                logger.info(f"Loaded FAISS index from {index_path} with {self.index.ntotal} vectors (pickle format)")

                # Auto-migrate to JSON format
                self._save()
                logger.info(f"Migrated docstore to JSON format: {json_docstore_path}")

            else:
                raise FileNotFoundError(f"No docstore found at {docstore_path} or {json_docstore_path}")

        except pickle.UnpicklingError as e:
            logger.error(f"Security error loading FAISS docstore: {e}")
            raise ValueError(f"Failed to load FAISS docstore: potentially malicious pickle file. {e}") from e
        except Exception as e:
            logger.warning(f"Failed to load FAISS index: {e}")
            self.docstore = {}
            self.index_to_id = {}

    def _save(self):
        """Save FAISS index and docstore to disk using JSON format (secure)."""
        if not self.path or not self.index:
            return

        try:
            os.makedirs(self.path, exist_ok=True)
            index_path = f"{self.path}/{self.collection_name}.faiss"
            json_docstore_path = f"{self.path}/{self.collection_name}.json"

View on GitHub (pinned to 001c235229)

Solutions

Restore or copy faiss.docstore.json (or legacy faiss.docstore) alongside the index file into the configured path
If the docstore is unrecoverable, delete the index too and rebuild the collection from source memories
Check the collection path config (absolute vs relative, trailing slash) and list the directory to confirm expected filenames

Example fix

# before
vs = FAISS(VectorStoreConfig(provider='faiss', config=FAISSConfig(path='/data/mem', collection_name='mem')))
# FileNotFoundError if /data/mem lacks faiss.docstore.json

# after
import os
assert os.path.exists('/data/mem/faiss.index')
assert os.path.exists('/data/mem/faiss.docstore.json'), 'copy the docstore too'

Defensive patterns

Strategy: validation

Validate before calling

import os

def faiss_store_complete(path):
    return all(
        os.path.exists(os.path.join(path, f))
        for f in ('faiss.index', 'faiss.docstore.json')
    )

Try / catch

try:
    vs = FAISS(config)
except FileNotFoundError as e:
    if 'No docstore found' in str(e):
        raise RuntimeError(f'Incomplete FAISS store at {config.path}: {e}') from e
    raise

Prevention

Copy collection directories atomically (index + docstore files together)
Include faiss.docstore.json in backup globs, not just *.index
Verify expected filenames exist before pointing FAISS at a path

When it happens

Trigger: Configuring FAISS with a path containing only the index file (e.g. after a partial copy, or someone deleted the docstore files), or a path where files are named differently than mem0 expects.

Common situations: Copying a collection directory incompletely between machines/containers; backup scripts that glob only *.index; OS-level case-sensitivity mismatch in filenames; empty path pointing at the wrong directory.

Related errors

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