Backup and restore error codes (mpbx-backup)
Raised by mpbx backup, mpbx restore, the scheduler and the /api/v1/system/backups routes
(W4-DEP-06). Messages name backup ids, part names, table names and error codes; they never contain
the passphrase, a key, a credential of the target, or a row. A failed run is also recorded in the
run history (error_code) and audited (backup.failed, backup.restore_failed,
backup.verify_failed). Guide: backup and restore.
| Code | Kind | Meaning | What to do |
|---|---|---|---|
MPBX-BACKUP-PASSPHRASE-WEAK | invalid_argument | A passphrase for creating backups has fewer than 12 characters, is blank, or is one repeated character. | Choose a longer one; a few random words are best. |
MPBX-BACKUP-PASSPHRASE-WRONG | invalid_argument | The passphrase does not open the backup, or its manifest.json was modified (the manifest MAC does not verify). Nothing was read or changed. | Use the passphrase the backup was made with (changing the settings later does not re-encrypt old backups). If you are sure it is right, the manifest was altered: restore another set. |
MPBX-BACKUP-PASSPHRASE-MISSING | invalid_argument | No passphrase was given, or it is empty. | Pass --passphrase-file, --passphrase-stdin, set MPBX_BACKUP_PASSPHRASE_FILE, or run on a terminal. There is deliberately no command-line flag for the passphrase itself. |
MPBX-BACKUP-CORRUPT | invalid_argument | A part is missing, its size or SHA-256 differs from the manifest, it is truncated, or a chunk fails authentication (damaged, truncated, reordered or replaced). Nothing was restored. | Restore another set; check the target (bucket versioning, disk). mpbx backup verify finds it without the passphrase. |
MPBX-BACKUP-NOT-FOUND | not_found | The backup set does not exist or has no manifest.json (incomplete), or the run id is unknown. | List the sets (mpbx backup list); an incomplete set is removed by the rotation after a day. |
MPBX-BACKUP-FORMAT | invalid_argument | manifest.json is not a valid manifest of a supported format version, or names an unknown part. | Use the mpbx version that made the backup, or restore another set. |
MPBX-BACKUP-SCHEMA-MISMATCH | invalid_argument | The database migrations of the backup are not exactly the ones this version knows, or a table or column differs. | Restore with the same mpbx version that made the backup, then upgrade. The rollback of an upgrade restores the pre-upgrade backup with the pre-upgrade version. |
MPBX-BACKUP-TARGET-NOT-EMPTY | conflict | The install already has users; a restore replaces ALL data. | Restore onto a fresh install, or pass --force if replacing it is what you want. |
MPBX-BACKUP-TARGET | unavailable / config | The backup target is misconfigured or unreachable (bucket missing, wrong endpoint or credentials, directory not writable). | Run "check target" in the console (POST /system/backups/settings/check-target) or mpbx backup list; the message names the failing step. |
MPBX-BACKUP-BUSY | conflict | Another backup or restore is running (on this or another node). | Wait, or look at GET /system/backups/runs. A run whose node died is abandoned after 12 hours (MPBX-BACKUP-ABANDONED on that run). |
MPBX-BACKUP-ABANDONED | (run record) | A run stayed running for 12 hours: its node died. Recorded on the run, not returned by a request. | None; the next run is not blocked. |
MPBX-BACKUP-POSTGRES | unavailable / config / internal | Reading or loading Postgres failed: connection, a table the login cannot read, a cycle in non-deferrable foreign keys, a table with partitions, a row count that does not match. A restore rolled back completely. | The message names the table and the database error. |
MPBX-BACKUP-CLICKHOUSE | unavailable | Reading or loading ClickHouse failed. Tables restored before the failure stay restored (ClickHouse has no transaction across tables). | Fix ClickHouse and run the restore again; it replaces the tables. |
MPBX-BACKUP-VALKEY | unavailable | Reading or writing Valkey failed in the optional Valkey part (MPBX_BACKUP_VALKEY=1). A restore replaced the keys written so far; the rest are untouched. | Fix Valkey and run the backup or restore again. |
MPBX-BACKUP-SECRETS | config | The install secrets are not available to the backup (no MPBX_MASTER_KEY), are unusable, or cannot be written to the sink on restore. | Run the backup where mpbx run gets its secrets (the same environment or --secrets-file). For a restore, mpbx init must have created the sink first; run the restore again after fixing it. |
MPBX-BACKUP-MASTER-KEY-MISMATCH | conflict | A console restore of a backup that holds a different master key than the running install. | Restore it with mpbx restore on the host, which also writes the backup's secrets. |
MPBX-BACKUP-CONFIRM | invalid_argument | The console restore's confirm is not the backup id. | Type the backup id. |
MPBX-BACKUP-KDF | invalid_argument | The key-derivation parameters in the manifest are outside what is accepted (a crafted manifest could ask for gigabytes of memory). | Use a backup made by mpbx. |
MPBX-BACKUP-USAGE | invalid_argument | A bad command line, request or target specification. | See mpbx backup --help. |
MPBX-BACKUP-SETTINGS | invalid_argument | The backup settings are invalid or incomplete: scheduled backups without a target or passphrase, a target that does not fit its backend, a retention that keeps nothing, no target configured for a backup/list/restore. | Fix the settings (PUT /system/backups/settings). |
MPBX-BACKUP-RESTORE-NOT-OWNER | config | The database login does not own the tables, so it cannot take them over for a restore. | Restore with the login that ran the migrations (the Compose and Kubernetes bundles use it for the application too). |
MPBX-BACKUP-RESTORE-BAD-TABLE | invalid_argument | A table name is not a plain identifier. | Report it: this is a bug or a crafted backup. |
MPBX-BACKUP-RESTORE-PROTECTION | internal | After the load, a trigger or forced row-level security could not be put back. The restore was rolled back. | Report it: the restore refuses to commit with a protection off. |