Códigos de error de respaldo y restauración (mpbx-backup)

Los genera mpbx backup, mpbx restore, el programador y las rutas /api/v1/system/backups (W4-DEP-06). Los mensajes indican ids de respaldo, nombres de partes, nombres de tablas y códigos de error; nunca contienen la frase de paso, una clave, una credencial del destino ni un registro. Una ejecución fallida también se registra en el historial de ejecuciones (error_code) y se audita (backup.failed, backup.restore_failed, backup.verify_failed). Guía: respaldo y restauración.

Código	Tipo	Significado	Qué hacer
MPBX-BACKUP-PASSPHRASE-WEAK	invalid_argument	La frase de paso para crear respaldos tiene menos de 12 caracteres, está en blanco o es un solo carácter repetido.	Elija una más larga; lo mejor son unas cuantas palabras aleatorias.
MPBX-BACKUP-PASSPHRASE-WRONG	invalid_argument	La frase de paso no abre el respaldo, o su manifest.json fue modificado (el MAC del manifiesto no se verifica). No se leyó ni cambió nada.	Use la frase de paso con la que se hizo el respaldo (cambiar la configuración después no vuelve a cifrar los respaldos anteriores). Si está seguro de que es la correcta, el manifiesto fue alterado: restaure otro conjunto.
MPBX-BACKUP-PASSPHRASE-MISSING	invalid_argument	No se indicó frase de paso, o está vacía.	Use --passphrase-file, --passphrase-stdin, configure MPBX_BACKUP_PASSPHRASE_FILE o ejecute desde una terminal. Deliberadamente no existe una opción de línea de comandos para la frase de paso en sí.
MPBX-BACKUP-CORRUPT	invalid_argument	Falta una parte, su tamaño o SHA-256 no coincide con el manifiesto, está truncada, o un fragmento no pasa la autenticación (dañado, truncado, reordenado o reemplazado). No se restauró nada.	Restaure otro conjunto; revise el destino (versionado del bucket, disco). mpbx backup verify lo detecta sin la frase de paso.
MPBX-BACKUP-NOT-FOUND	not_found	El conjunto de respaldo no existe o no tiene manifest.json (está incompleto), o el id de ejecución es desconocido.	Liste los conjuntos (mpbx backup list); un conjunto incompleto lo elimina la rotación después de un día.
MPBX-BACKUP-FORMAT	invalid_argument	manifest.json no es un manifiesto válido de una versión de formato compatible, o nombra una parte desconocida.	Use la versión de mpbx que hizo el respaldo, o restaure otro conjunto.
MPBX-BACKUP-SCHEMA-MISMATCH	invalid_argument	Las migraciones de base de datos del respaldo no son exactamente las que conoce esta versión, o una tabla o columna es distinta.	Restaure con la misma versión de mpbx que hizo el respaldo y después actualice. La reversión de una actualización restaura el respaldo previo a la actualización con la versión previa.
MPBX-BACKUP-TARGET-NOT-EMPTY	conflict	La instalación ya tiene usuarios; una restauración reemplaza TODOS los datos.	Restaure en una instalación nueva, o use --force si lo que quiere es reemplazarla.
MPBX-BACKUP-TARGET	unavailable / config	El destino del respaldo está mal configurado o no es accesible (bucket inexistente, endpoint o credenciales incorrectos, directorio no escribible).	Ejecute "verificar destino" en la consola (POST /system/backups/settings/check-target) o mpbx backup list; el mensaje indica el paso que falla.
MPBX-BACKUP-BUSY	conflict	Otro respaldo o restauración se está ejecutando (en este nodo u otro).	Espere, o revise GET /system/backups/runs. Una ejecución cuyo nodo murió se abandona después de 12 horas (MPBX-BACKUP-ABANDONED en esa ejecución).
MPBX-BACKUP-ABANDONED	(registro de ejecución)	Una ejecución permaneció en running durante 12 horas: su nodo murió. Se registra en la ejecución, no la devuelve una solicitud.	Ninguna; la siguiente ejecución no se bloquea.
MPBX-BACKUP-POSTGRES	unavailable / config / internal	Falló la lectura o la carga de Postgres: conexión, una tabla que el usuario no puede leer, un ciclo en llaves foráneas no diferibles, una tabla con particiones o un conteo de filas que no coincide. Una restauración se revirtió por completo.	El mensaje indica la tabla y el error de la base de datos.
MPBX-BACKUP-CLICKHOUSE	unavailable	Falló la lectura o la carga de ClickHouse. Las tablas restauradas antes del fallo siguen restauradas (ClickHouse no tiene transacciones entre tablas).	Corrija ClickHouse y ejecute la restauración de nuevo; reemplaza las tablas.
MPBX-BACKUP-VALKEY	unavailable	Falló la lectura o la escritura de Valkey en la parte opcional de Valkey (MPBX_BACKUP_VALKEY=1). Una restauración reemplazó las claves escritas hasta ese momento; las demás no se tocaron.	Corrija Valkey y ejecute de nuevo el respaldo o la restauración.
MPBX-BACKUP-SECRETS	config	Los secretos de instalación no están disponibles para el respaldo (falta MPBX_MASTER_KEY), no son utilizables o no se pueden escribir en el destino durante la restauración.	Ejecute el respaldo donde mpbx run obtiene sus secretos (el mismo entorno o --secrets-file). Para una restauración, mpbx init debe haber creado antes el destino; ejecute la restauración de nuevo después de corregirlo.
MPBX-BACKUP-MASTER-KEY-MISMATCH	conflict	Una restauración desde la consola de un respaldo que tiene una clave maestra distinta de la instalación en ejecución.	Restáurelo con mpbx restore en el host, que también escribe los secretos del respaldo.
MPBX-BACKUP-CONFIRM	invalid_argument	El confirm de la restauración desde la consola no es el id del respaldo.	Escriba el id del respaldo.
MPBX-BACKUP-KDF	invalid_argument	Los parámetros de derivación de clave del manifiesto están fuera de lo aceptado (un manifiesto manipulado podría pedir gigabytes de memoria).	Use un respaldo hecho por mpbx.
MPBX-BACKUP-USAGE	invalid_argument	Línea de comandos, solicitud o especificación de destino incorrectas.	Consulte mpbx backup --help.
MPBX-BACKUP-SETTINGS	invalid_argument	La configuración de respaldos no es válida o está incompleta: respaldos programados sin destino o frase de paso, un destino que no corresponde a su backend, una retención que no conserva nada, o ningún destino configurado para respaldar, listar o restaurar.	Corrija la configuración (PUT /system/backups/settings).
MPBX-BACKUP-RESTORE-NOT-OWNER	config	El usuario de la base de datos no es dueño de las tablas, así que no puede tomarlas para una restauración.	Restaure con el usuario que ejecutó las migraciones (los paquetes de Compose y Kubernetes lo usan también para la aplicación).
MPBX-BACKUP-RESTORE-BAD-TABLE	invalid_argument	Un nombre de tabla no es un identificador simple.	Repórtelo: es un error o un respaldo manipulado.
MPBX-BACKUP-RESTORE-PROTECTION	internal	Después de la carga, no se pudo volver a activar un disparador o la seguridad a nivel de fila forzada. La restauración se revirtió.	Repórtelo: la restauración se niega a confirmarse con una protección desactivada.