MemPalace/mempalace · error · ValueError

backup belongs to collection {backup_collection!r}, not {tar

Error message

backup belongs to collection {backup_collection!r}, not {target_collection!r}

What it means

Raised during restore-from-backup when the backup header's 'collection' name differs from the target ChromaDB collection being restored into. The check (backup_collection and target_collection and backup != target) only fires when both names are known — a headerless/anonymous backup is allowed — but a concrete mismatch is refused because replaying another collection's documents would attach verbatim content to the wrong wing/room structure. The message names both collections with !r quoting.

Source

Thrown at mempalace/encoding_repair.py:585

def restore_collection(
    collection,
    backup_path: Union[str, Path],
    *,
    batch_size: int = 500,
) -> dict:
    """Restore original documents from an encoding-repair backup."""
    if batch_size < 1:
        raise ValueError("batch_size must be at least 1")

    path = Path(backup_path)
    header = _read_backup_header(path)

    backup_collection = header.get("collection")
    target_collection = _collection_name(collection)

    if backup_collection and target_collection and backup_collection != target_collection:
        raise ValueError(
            f"backup belongs to collection {backup_collection!r}, not {target_collection!r}"
        )

    # Validate the complete file before performing the first restore write.
    validated = sum(1 for _record in _iter_backup_records(path))

    restored = 0
    batch_ids = []
    batch_documents = []

    for (
        drawer_id,
        document,
    ) in _iter_backup_records(path):
        batch_ids.append(drawer_id)
        batch_documents.append(document)

        if len(batch_ids) < batch_size:

View on GitHub (pinned to 06cb6987f0)

Solutions

Check both names in the message; use the backup against the collection it was created from
If the target collection was renamed, pass the original collection handle (or rename back) so names align
If you truly intend cross-collection restore, copy the backup and edit its header's 'collection' field to the target name — only when you are certain the documents belong there
List backups with their headers: head -1 each backup file to see its 'collection' value

Example fix

# before
restore_backup(new_collection, backup_path='backup-of-old-palace.jsonl')
# ValueError: backup belongs to collection 'palace_old', not 'palace_new'

# after: retarget deliberately
import json
lines = open('backup.jsonl', encoding='utf-8').read().splitlines()
h = json.loads(lines[0]); h['collection'] = 'palace_new'
open('backup-retargeted.jsonl', 'w', encoding='utf-8').write(
    json.dumps(h) + '\n' + '\n'.join(lines[1:]) + '\n')
restore_backup(new_collection, backup_path='backup-retargeted.jsonl')

Defensive patterns

Strategy: validation

Validate before calling

import json

def backup_matches_collection(path, collection_name: str) -> bool:
    header = json.loads(open(path, encoding='utf-8').readline())
    bc = header.get('collection')
    return not bc or bc == collection_name  # anonymous backups are allowed through

Try / catch

try:
    restore_backup(collection, backup_path=path)
except ValueError as e:
    if "belongs to collection" in str(e):
        sys.exit("Wrong backup for this collection — locate the matching one (head -1 each backup)")

Prevention

Name backup files after their collection (e.g. palace-main.backup.jsonl)
Record the collection name in your restore runbook alongside the backup path
Check head -1 <backup> before any restore to confirm the 'collection' field

When it happens

Trigger: Calling restore_backup(collection, backup_path=...) with a backup file produced by a repair of a different palace (e.g. a test palace, an old export, or another user profile), or after the collection was renamed/recreated with a different name.

Common situations: Multiple palaces on one machine (work vs personal) and backup paths mixed up; restoring a backup archived from a pre-migration collection name; CI tests reusing fixture backups against freshly named collections.

Related errors

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