MPBX-UPGRADE-USAGE | invalid_argument | Bad command line (exit 2). | See mpbx upgrade --help, mpbx config --help, mpbx selftest --help. |
MPBX-UPGRADE-MANIFEST | invalid_argument | A release.json is malformed, of an unknown format, lists more than two direct sources (N-2), lists a source that is not older, has an image reference that is not one, or a target release has no ports contract while the installed one has. | Use the bundle as published; a release manifest is written by build-bundle.sh, not by hand. |
MPBX-UPGRADE-SAME-VERSION | refusal | The bundle is the installed release. | Nothing to do. To repair files of the same release, re-run the installer. |
MPBX-UPGRADE-DOWNGRADE | refusal | The bundle is older than the installed release. | Going back is a rollback: mpbx-ctl rollback restores the pre-upgrade snapshot. An older binary never runs on a newer schema. |
MPBX-UPGRADE-SKIP | refusal | The installed release is not one the target upgrades from directly (more than two releases back, N-2, DECISIONS Round 5). The message names the release to install first. | Upgrade to the named intermediate release, then to the target. |
MPBX-UPGRADE-CHANNEL | refusal | The target is on another channel (stable, beta, nightly) than the install. | Pass --allow-channel-change if switching channels is what you want. |
MPBX-UPGRADE-BREAKING-PORTS | refusal | A default port differs between the releases (PLAT-UPD-007). Undeclared: never installable. Declared (breaking: ["ports"]): needs --accept-breaking. | Read the release notes, update firewalls, trunks and clients, then accept. |
MPBX-UPGRADE-BREAKING | refusal | The target declares other breaking changes. | Read the release notes, then pass --accept-breaking. |
MPBX-UPGRADE-RELEASE-MISMATCH | refusal | The bundle's release.json does not describe the image it names: another release version is baked into the binary, or another newest migration. | The bundle and images.env do not belong together; use the images of the bundle's release. |
MPBX-UPGRADE-SCHEMA-AHEAD | refusal | The database has migrations the target does not know: it is newer than the target (an upgrade that was abandoned without a rollback, or a downgrade attempt). | Roll back the newer upgrade first (mpbx-ctl rollback). |
MPBX-UPGRADE-SCHEMA-MODIFIED | refusal | An applied migration differs from the target's file (migrations are append-only). | Do not install this release over this database; report it. |
MPBX-UPGRADE-SCHEMA-DIRTY | refusal | A migration is recorded as failed half way. | Restore the last backup, then upgrade. |
MPBX-UPGRADE-DB-VERSION | refusal | Postgres, ClickHouse or Valkey is older than the target release supports (requires in its release.json, W7-PLAT-01a). The message names the service, its version and the minimum. | Upgrade that service first. The bundled ones come with the bundle; an external one (Kubernetes external-db) is upgraded by whoever runs it. |
MPBX-UPGRADE-CERT-EXPIRED | refusal | An active install-wide TLS certificate has expired; the upgrade restarts the edge onto it. Company certificates are not checked. | Renew it or upload a new one (admin console, Certificates; certificates), or pass --accept-expired-cert if the upgrade must go ahead. |
MPBX-UPGRADE-SETTING-REMOVED | refusal | An environment variable that the target release no longer reads is set (deprecated in its release.json). The message says what replaces it. | Move to the new setting in .env, then upgrade. A variable that is only deprecated is listed as a note, not refused. |
MPBX-UPGRADE-DATABASE | unavailable | Postgres (or ClickHouse) could not be read for the check, the export or the self-test. | The message names the step; check that the databases run (mpbx-ctl ps). |
MPBX-UPGRADE-EXPORT-DIFFERS | (result) | mpbx config export --compare found tables that differ (exit 1); they are listed. After a rollback this means the restore did not bring back the pre-upgrade configuration. | Look at the listed tables. The post-upgrade data is kept in the mpbx_pre_rollback_* databases and the safety backup. |
MPBX-UPGRADE-EXPORT-FORMAT | invalid_argument | The file given to --compare is not a config export of a supported format. | Compare with the config-export.json of the snapshot. |
MPBX-SELFTEST-FAILED | (result) | A self-test check failed (exit 1); each line names the check. After an upgrade the gate offers the rollback (or runs it with --auto-rollback). | See the failing line: postgres-login (a superuser or BYPASSRLS login: isolation is off), rls-probe (the login sees company rows without a company), postgres-schema, schema-lint, valkey, clickhouse, http, auth-gate, sign-in. |