{"record":{"id":"1593dda43f40c67d","repo":"MemPalace/mempalace","slug":"unsupported-repair-backup-format","errorCode":null,"errorMessage":"unsupported repair backup format","messagePattern":"unsupported repair backup format","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"mempalace/encoding_repair.py","lineNumber":391,"sourceCode":"    try:\n        with path.open(\n            \"r\",\n            encoding=\"utf-8\",\n        ) as handle:\n            header = json.loads(handle.readline())\n    except OSError as exc:\n        raise ValueError(f\"could not read repair backup: {path}\") from exc\n    except (\n        json.JSONDecodeError,\n        TypeError,\n    ) as exc:\n        raise ValueError(\"repair backup has an invalid header\") from exc\n\n    if not isinstance(\n        header,\n        dict,\n    ) or (header.get(\"format\") != _BACKUP_FORMAT or header.get(\"version\") != _BACKUP_VERSION):\n        raise ValueError(\"unsupported repair backup format\")\n\n    return header\n\n\ndef _iter_backup_records(\n    path: Path,\n) -> Iterator[tuple[str, str]]:\n    _read_backup_header(path)\n\n    with path.open(\n        \"r\",\n        encoding=\"utf-8\",\n    ) as handle:\n        # Skip the validated header.\n        handle.readline()\n\n        for line_number, line in enumerate(\n            handle,","sourceCodeStart":373,"sourceCodeEnd":409,"githubUrl":"https://github.com/MemPalace/mempalace/blob/06cb6987f02610784fefbad4b2bd5d026d164ba6/mempalace/encoding_repair.py#L373-L409","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the header: head -1 backup.jsonl — compare 'format' and 'version' against what your mempalace version writes","Install the mempalace version that created the backup (check the backup's creation date vs your changelog), restore under it, then upgrade","If this file is not an encoding-repair backup, locate the correct one (repair_collection reports backup_path when it runs)","Regenerate the backup by re-running the repair flow on the current version instead of restoring an old one"],"exampleFix":"# before\npip install -U mempalace\nrestore_backup(collection, backup_path='old-v1-backup.jsonl')  # ValueError: unsupported\n# after: pin the version that wrote it\npip install mempalace==<version-that-created-backup>\nrestore_backup(collection, backup_path='old-v1-backup.jsonl')","handlingStrategy":"validation","validationCode":"import json\nfrom mempalace import encoding_repair as er\n\ndef backup_version_ok(path) -> bool:\n    header = json.loads(open(path, encoding='utf-8').readline())\n    return (isinstance(header, dict)\n            and header.get('format') == er._BACKUP_FORMAT\n            and header.get('version') == er._BACKUP_VERSION)","typeGuard":null,"tryCatchPattern":"try:\n    restore_backup(collection, backup_path=path)\nexcept ValueError as e:\n    if \"unsupported repair backup format\" in str(e):\n        sys.exit(\"Backup from a different mempalace version — reinstall that version to restore\")","preventionTips":["Tag backup files with the mempalace version that wrote them (in filename or a sidecar)","Upgrade and restore within the same maintenance window, or test restores after every upgrade","Store backups with the palace they belong to so version context is preserved"],"tags":["backup","versioning","repair","data-integrity"],"backgroundTag":null,"analyzedSha":"06cb6987f02610784fefbad4b2bd5d026d164ba6","analyzedAt":"2026-08-15T03:03:36.213Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}