Skip to content

Troubleshooting: Migration

Preflight blockers

Each blocker code maps to a catalog entry. Common ones:

  • TARGET_OFFLINE, TARGET_MAINTENANCE — bring the target online / out of maintenance.
  • INSUFFICIENT_CPU, INSUFFICIENT_RAM, INSUFFICIENT_STORAGE — free capacity or choose another target.
  • CPU_PROFILE_INCOMPATIBLE, NUMA_REQUIREMENT_UNMET, HUGEPAGE_UNAVAILABLE — the target cannot satisfy the instance's compute intent.
  • NETWORK_UNAVAILABLE, VLAN_UNAVAILABLE, IP_NOT_PORTABLE, PRIVATE_NETWORK_LOCALITY — the target network cannot carry the instance.
  • SNAPSHOT_STATE_UNSUPPORTED — remove snapshots or use a cold move.

Host-bound hardware

Symptom: GPU_HOST_BOUND, HARDWARE_PASSTHROUGH_BOUND. A GPU/PCI passthrough binding ties the instance to its host. Automated migration is not possible; manual recovery is required.

Recovery required

Symptom: RECOVERY_REQUIRED, ROLLBACK_FAILED. The migration is in a state that needs operator recovery. Follow the migration recovery runbook; do not retry blindly.

php artisan pterocloud:migration:recover <migration_uuid>
php artisan pterocloud:migration:health --json

Honesty reminder

Live migration and disk transfer are not tested on physical hardware in this build. Treat a successful preflight as readiness, not proof.