mivama docs
Mivama Docs / migration

States & recovery

Validation, rollback and failures

Last verified 8 August 2026 · source-backed

Migration commands are state-dependent. MIGRATION_STATE_CONFLICT means the caller requested an operation that is unsafe in the current state; it is a guard, not a generic server failure.

State model

Exact labels in UI may be normalized for customers; Core status and phase fields remain authoritative.

Command guards

  • Scan requires an active connected token.
  • Begin import requires a complete, validated manifest/upload.
  • Final sync requires successful initial import and explicit review approval.
  • Repeating a consumed one-time code returns unauthorized.
  • A plugin token for another migration/service returns unauthorized.
  • Completed, expired or disconnected migrations reject write commands.

HTTP 401 usually means missing, expired, disconnected or mismatched connector authentication. HTTP 417 can carry a Frappe validation error. Portal/plugin should unwrap the Core message rather than display only the status number.

Recovery principles

Do not advance status manually to silence a conflict. Inspect the record, event timeline, upload state, gateway logs, worker command/result and target health. Then retry the narrow operation that failed.

Import and final sync create rollback material before target mutation. If validation fails, the worker restores the target backup and reports rollback outcome separately. A rollback failure is high severity because the target may be inconsistent; prevent cutover and require operator review.

Common checks

  1. Confirm Mivama Hosting Migration exists and belongs to the service/customer.
  2. Compare connector migration ID with the active record.
  3. Check token expiry/disconnected flags and server time.
  4. Verify expected chunk count, checksums and manifest completion.
  5. Inspect migration gateway and worker systemd journals.
  6. Confirm target Compose project, correct tenant user and free disk.
  7. Check WordPress health and rewritten home/siteurl after import.

Expiry

The hourly scheduler expires stale migrations. Expiry revokes access and makes temporary uploads eligible for cleanup. Starting over creates a new migration/code rather than reviving an old transfer capability.