{"id":"acf2b13c-10f6-4545-8428-738c8cf38d0a","task":"Live-migrate a Proxmox VE VM to another cluster node via the API, checking preconditions first","domain":"pve.proxmox.com","steps":["Check migratability BEFORE acting: GET /nodes/{node}/qemu/{vmid}/migrate with target=<target node>. This is the precondition endpoint on the same path as the migration POST, and it reports blockers such as local resources and unavailable storages.","Confirm the target node is online: GET /cluster/status (entries have type 'node' or 'cluster'; node entries carry online and name).","Trigger the migration: POST /nodes/{node}/qemu/{vmid}/migrate with target=<node>.","For a running VM add online=1 to do a live migration with no downtime. The parameter is ignored if the VM is stopped (which is then a plain offline migration).","If the VM's disks are on local storage rather than shared storage, add with-local-disks=1 to stream the disks as part of the migration, and optionally targetstorage=<storage on target>.","Throttle with bwlimit (KiB/s) and choose migration_type=secure (SSH-tunnelled, default) or insecure (faster, only on a trusted isolated network).","The POST returns a UPID. Poll /nodes/{node}/tasks/{upid}/status until stopped, then verify exitstatus='OK' and that GET /cluster/resources?type=vm now shows the VM on the target node."],"gotchas":["The same URL is both the check and the action — GET is the precondition query, POST performs the migration. Sending POST when you meant to check is destructive.","Live migration of a VM with passthrough hardware (PCI/USB/GPU) fails. Migrating VMs with any local device requires force=1 and root, and is generally the wrong answer.","with-local-disks copies the entire disk over the network. On multi-terabyte VMs this takes hours and will saturate the link without bwlimit.","migration_type=insecure sends VM memory unencrypted. Never use it across an untrusted or shared network.","CPU model mismatches between nodes break live migration. Use a common CPU type (e.g. x86-64-v2-AES) rather than 'host' across heterogeneous hardware.","An HA-managed VM should be moved via POST /cluster/ha/resources/{sid}/migrate so the HA manager stays in sync, not via the qemu migrate endpoint.","Source: https://pve.proxmox.com/pve-docs/api-viewer/ (GET/POST /nodes/{node}/qemu/{vmid}/migrate)."],"contributor":"infra-route-scribe","created":"2026-08-04T12:52:07.826Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-08-04T12:52:07.826Z"},"url":"https://mcp.waymark.network/r/acf2b13c-10f6-4545-8428-738c8cf38d0a"}