MemPalace/mempalace · error · ValueError

unsupported repair backup format

Error message

unsupported repair backup format

What it means

Raised by _read_backup_header when the header line is valid JSON but is not a dict, or its 'format'/'version' fields do not match the constants _BACKUP_FORMAT/_BACKUP_VERSION the current code expects. This is a deliberate version gate: restore logic is coupled to the exact backup layout, and attempting to replay a foreign or older backup could corrupt the collection, so mismatched files are rejected up front.

Source

Thrown at mempalace/encoding_repair.py:391

    try:
        with path.open(
            "r",
            encoding="utf-8",
        ) as handle:
            header = json.loads(handle.readline())
    except OSError as exc:
        raise ValueError(f"could not read repair backup: {path}") from exc
    except (
        json.JSONDecodeError,
        TypeError,
    ) as exc:
        raise ValueError("repair backup has an invalid header") from exc

    if not isinstance(
        header,
        dict,
    ) or (header.get("format") != _BACKUP_FORMAT or header.get("version") != _BACKUP_VERSION):
        raise ValueError("unsupported repair backup format")

    return header


def _iter_backup_records(
    path: Path,
) -> Iterator[tuple[str, str]]:
    _read_backup_header(path)

    with path.open(
        "r",
        encoding="utf-8",
    ) as handle:
        # Skip the validated header.
        handle.readline()

        for line_number, line in enumerate(
            handle,

View on GitHub (pinned to 06cb6987f0)

Solutions

1. Check the header: head -1 backup.jsonl — compare 'format' and 'version' against what your mempalace version writes
2. Install the mempalace version that created the backup (check the backup's creation date vs your changelog), restore under it, then upgrade
3. If this file is not an encoding-repair backup, locate the correct one (repair_collection reports backup_path when it runs)
4. Regenerate the backup by re-running the repair flow on the current version instead of restoring an old one

Example fix

# before
pip install -U mempalace
restore_backup(collection, backup_path='old-v1-backup.jsonl')  # ValueError: unsupported
# after: pin the version that wrote it
pip install mempalace==<version-that-created-backup>
restore_backup(collection, backup_path='old-v1-backup.jsonl')

import json
from mempalace import encoding_repair as er

def backup_version_ok(path) -> bool:
    header = json.loads(open(path, encoding='utf-8').readline())
    return (isinstance(header, dict)
            and header.get('format') == er._BACKUP_FORMAT
            and header.get('version') == er._BACKUP_VERSION)

try:
    restore_backup(collection, backup_path=path)
except ValueError as e:
    if "unsupported repair backup format" in str(e):
        sys.exit("Backup from a different mempalace version — reinstall that version to restore")

When it happens

Trigger: Restoring a backup produced by a different (older or newer) mempalace version whose header constants differ; feeding an arbitrary JSONL file as backup_path; a backup from a different tool that happens to be JSONL.

Common situations: Upgrading mempalace and trying to restore pre-upgrade backups; copying backups between machines with different mempalace versions; passing a drawer export file where the backup file was expected.

Related errors

• repair backup has an invalid header
• invalid backup JSON at line {line_number}
• could not read repair backup: {path}
• invalid repair backup record at line {line_number}
• backup belongs to collection {backup_collection!r}, not {tar

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