MemPalace/mempalace · error · ValueError

update requires at least one of documents, metadatas, embedd

Error message

update requires at least one of documents, metadatas, embeddings

What it means

Raised as RebuildCleanupError when the final cleanup stage (FTS5 index rebuild + VACUUM + quick_check, strict=True) fails after all data rows were already successfully rebuilt into the destination palace. The data is intact but the derived index may be malformed, so the operation cannot report success. The message tells you where the recovered palace and the original (archived or unchanged) live.

Source

Thrown at mempalace/backends/base.py:560

        where: Optional[dict] = None,
    ) -> LexicalResult:
        raise UnsupportedCapabilityError("backend does not support lexical_search")

    def update(
        self,
        *,
        ids: list[str],
        documents: Optional[list[str]] = None,
        metadatas: Optional[list[dict]] = None,
        embeddings: Optional[list[list[float]]] = None,
    ) -> None:
        """Default non-atomic update: get + merge + upsert.

        Backends advertising ``supports_update`` MUST override with an atomic
        single-round-trip implementation.
        """
        if documents is None and metadatas is None and embeddings is None:
            raise ValueError("update requires at least one of documents, metadatas, embeddings")

        n = len(ids)
        for label, value in (
            ("documents", documents),
            ("metadatas", metadatas),
            ("embeddings", embeddings),
        ):
            if value is not None and len(value) != n:
                raise ValueError(f"{label} length {len(value)} does not match ids length {n}")

        existing = self.get(ids=ids, include=["documents", "metadatas"])
        by_id = {
            rid: (existing.documents[i], existing.metadatas[i])
            for i, rid in enumerate(existing.ids)
        }
        merged_docs: list[str] = []
        merged_metas: list[dict] = []
        for i, rid in enumerate(ids):

View on GitHub (pinned to 06cb6987f0)

Solutions

Free disk space (VACUUM needs headroom comparable to the DB size) and close any process holding the recovered chroma.sqlite3.
Keep the recovered palace at dest_palace — the row data is fully rebuilt; only the derived index is suspect.
Re-run the FTS5 rebuild / VACUUM manually against dest_palace, or re-run the recovery which will redo cleanup.
If cleanup still fails, fall back to the archived original (archive_path) or the unchanged source palace.

Defensive patterns

Strategy: try-catch

Validate before calling

import shutil
if shutil.disk_usage(dest_palace).free < db_size:
    raise SystemExit('VACUUM needs free space ~ DB size')

Try / catch

try:
    run_recovery(...)
except RebuildCleanupError as e:
    # row data is intact at e.dest_palace; only derived index is suspect
    close_holders_and_rerun_cleanup(e.dest_palace)

Prevention

Free disk headroom (~2x DB size) before recovery runs.
Close all processes holding chroma.sqlite3 during recovery.
Do not delete the recovered palace after this error — data is already rebuilt.

When it happens

Trigger: _vacuum_and_rebuild_fts5(dest_palace, strict=True) raises — locked SQLite file, disk exhaustion during VACUUM (which needs free space roughly equal to the DB size), or a quick_check failure after upserts.

Common situations: VACUUM failing on a full disk; another process (MCP server, miner) holding chroma.sqlite3 during recovery; FTS5 index corruption left behind by interrupted bulk upserts.

Related errors

AI-assisted analysis of MemPalace/mempalace@06cb6987f0 (2026-08-15). Data as JSON: /api/errors/9eb6509da4da7b95. Report an issue: GitHub.