Known Limitations

This page documents known limitations, unsupported configurations, and important caveats in vJailbreak. Review this page before planning a migration to avoid unexpected failures.

Windows Dynamic Disk (LDM)

Windows VMs whose system volume sits on a dynamic disk (Logical Disk Manager / LDM) are supported, but they follow a dedicated migration path. virt-v2v cannot convert these guests, so vJailbreak skips conversion, brings the VM up on an emulated SATA controller, and waits at the LDM Boot Verification phase for you to move it to virtio.

vJailbreak detects this automatically — there is nothing to select in the migration form.

Configuration	Result
Root: Basic, Data: LDM	Migrates normally — import LDM data disks in Windows post-migration
Root: LDM, Data: Basic	Supported via the SATA-first path — manual cutover required
Root: LDM, Data: LDM	Supported via the SATA-first path — manual cutover required

The following limitations apply when the system volume is on LDM:

Limitation	Detail
Conversion-time features do not run	VMware Tools removal, network persistence and user firstboot scripts are all performed by virt-v2v during conversion. Conversion is skipped, so these must be handled manually inside the guest.
VirtIO drivers must be pre-installed	Drivers cannot be injected offline into an LDM volume. Install the VirtIO guest tools on the source VM before migrating.
The SAN policy must be set beforehand	Without san policy=onlineall, Windows brings the migrated disks up offline and the LDM volume set is left broken.
The migration requires manual intervention	The migration pauses at LDM Boot Verification until you confirm the VM booted. There is no timeout, so the migration will not complete unattended.

See the full guide: Windows Dynamic Disk (LDM) Migration.

Active Directory-Joined VMs

Domain Controllers

Migrating Active Directory Domain Controller VMs is strongly not recommended. The core risk is specific to how vJailbreak works: virt-v2v performs a disk-level conversion and creates a new VM on a different hypervisor. VM-GenerationID — the hypervisor metadata that Windows Server 2012+ uses to detect unsafe restores — is not stored on disk and is not preserved through this process. The migrated DC starts with a new (or absent) VMGenID, which Windows AD treats as an unsafe restore/clone.

What happens depends on the Windows version:

• Windows Server 2012 and later: The lost VMGenID triggers Windows’ built-in safeguards. The DC automatically resets its invocation ID and forces a non-authoritative resync against replication partners. The domain may recover if other DCs are reachable, but this is unreliable in production and is not a supported migration path.
• Windows Server 2008 R2 and earlier (no VMGenID support): A genuine USN rollback can occur. The domain silently stops accepting replication from the migrated DC, and the AD environment can diverge without obvious errors. This is difficult to detect and hard to recover from.

In both cases the source DC must be permanently removed from the domain before or immediately after the migrated copy is brought online. Running both simultaneously on the same domain will corrupt AD.

Recommended approach (from Microsoft guidance):

1. Provision a new DC in the target OpenStack environment using standard AD promotion.
2. Let AD replication populate it from an existing domain controller.
3. Decommission the source DC via dcpromo or Server Manager once replication is verified complete.

If you must migrate a DC (lab/test environments, single-DC setups with no alternative), take these precautions:

• Cleanly shut down the source DC before migration — do not snapshot a running DC.
• Migrate only one DC at a time.
• After the migrated DC boots, verify replication health immediately:

  repadmin /replsummary
  dcdiag /test:replications

• Confirm time synchronization (Kerberos requires clocks within 5 minutes of each other).
• Verify DNS is resolving correctly for all domain members.
• Decommission the source DC immediately — never run the original and migrated DC on the same domain simultaneously.

Member Servers and Workstations

Migrating domain-joined member VMs (non-DC servers and workstations) is generally safe. The machine account password is stored in the VM’s own LSA secrets and is copied with the disk, so domain membership typically survives the migration intact.

A few edge cases can cause domain authentication to fail post-migration:

• Kerberos clock skew: If the migrated VM’s clock is more than 5 minutes off from the domain controller, Kerberos authentication will fail. Sync the VM’s clock immediately after boot.
• DNS resolution failures: The VM must be able to resolve the domain controller’s name and locate AD SRV records. Verify DNS settings after migration.
• Pre-existing stale computer account: If the source VM had been offline for an extended period (typically 90+ days) before migration, the domain controller may have already invalidated its computer account. This is a pre-existing condition unrelated to the migration itself.

If users see The trust relationship between this workstation and the primary domain failed after migration, run the following to reset the account:

# Option 1 — reset computer account password without rejoining
netdom resetpwd /server:<domain-controller> /userd:<domain\admin> /passwordd:*

# Option 2 — rejoin the domain
Remove-Computer -WorkgroupName WORKGROUP -Force
Add-Computer -DomainName <domain> -Credential <domain\admin> -Restart

Persist Network: Windows Server 2012 and Below

The Persist source network interfaces option does not work for Windows Server 2012 and earlier (including Windows Server 2008 R2 and Windows Server 2008).

Network interface name persistence depends on PowerShell capabilities, the Windows registry structure for network adapters, and a compatible version of pnputil. These prerequisites are not met on Windows Server 2012 and earlier.

Workaround: Manually reconfigure network interface names and static IP settings inside the VM after migration.

Assign IP and Persist Network Cannot Be Used Together

The Assign IP and Persist Network (Persist source network interfaces) options are mutually exclusive. Enabling both simultaneously produces undefined behavior and the migration may not apply either setting correctly.

Rule: Use one or the other — not both.

• Use Assign IP when you need to set a specific IP address on the destination VM.
• Use Persist Network when you need to preserve the source VM’s interface names and static routes.

Multi-IP Assignment Not Supported

Only one IP address per network interface is supported in the Assign IPs field. The UI enforces this — the field accepts a single IP per interface. If multiple IPs are specified via CLI, the migration will fail.

Workaround: Assign additional IPs manually inside the VM after migration, or use OpenStack port configuration to attach additional floating IPs post-migration.

VMware Tools Removal: Residual Artifacts

The VMware Tools removal process performed by virt-v2v during migration may leave behind residual files and registry entries on the destination VM.

These artifacts are typically harmless but may appear in application logs or security scans.

For a full list of known residual artifacts and cleanup steps, see: VMware Residual Artifacts.

Multi-Boot VMs Not Supported

vJailbreak does not support VMs with multiple bootable operating systems (multi-boot configurations). virt-v2v inspects only a single OS installation per VM and cannot convert multi-boot disk layouts.

Workaround: Migrate each OS as a separate VM, or convert the disk to a single-boot configuration before migration.

SUSE Linux (SLES / SLED) with Legacy GRUB 0.97

Older SUSE-family VMs — SLES, SLED, and other SUSE distributions — that still boot with legacy GRUB (0.97) require special handling. These are typically BIOS VMs on a multi-disk layout, where the first boot stage sits in one disk’s MBR while its second stage and /boot live on a separate disk. After migration to KVM, the virtual disks are re-numbered and no longer match the original VMware ordering, so GRUB cannot find its second stage and the VM fails to boot with GRUB Error 21.

In such scenarios, we recommend upgrading to GRUB2.

Why we upgrade GRUB: GRUB 0.97 is too old and fragile — it hard-codes disk numbers and block offsets that break the moment the hypervisor re-orders disks. virt-v2v also can’t reconfigure GRUB 0.97 for KVM; it only manages GRUB2.

NOTE: On these older SUSE releases GRUB2 ships only as an EFI build (no legacy-BIOS version), so upgrading GRUB forces a switch to UEFI.

RHEL 7 Guests Missing GRUB Compatibility Symlink

Some RHEL 7.x guests are missing the /boot/grub/grub.cfg compatibility symlink that grubby (used internally by virt-v2v-in-place) expects to point at /boot/grub2/grub.cfg. GRUB2 itself is configured correctly — only this symlink is missing — and conversion fails with:

libguestfs error: command:
error opening /boot/grub/grub.cfg for read:
No such file or directory

Workaround: Verify and, if needed, recreate the symlink before migrating. See virt-v2v-in-place fails on RHEL 7 for details.

Hotplug Flavor Requirements

OpenStack hotplug (live CPU/RAM resize without VM reboot) is supported post-migration, but only if the VM is migrated with a hotplug-capable flavor.

To use hotplug after migration:

1. Platform9 Private Cloud Director (PCD): PCD provides a hotplug base flavor named hotplug by default. While triggering the migration in vJailbreak, select the hotplug flavor for the VMs that need live resize.

2. Other OpenStack environments: ask your OpenStack admin to create a flavor with hotplug-enabled extra specs, for example:

   openstack flavor set <flavor-name> \
     --property hw:cpu_policy=mixed \
     --property hw:cpu_max_vcpus=<max> \
     --property hw:mem_page_size=any

   Then assign this flavor in the vJailbreak migration form before starting the migration.

3. After migration, resize the VM in OpenStack using the hotplug capability.

Hotplug Metadata and Resize Headroom

When a hotplug base flavor (0 vCPU, 0 RAM — such as PCD’s default hotplug flavor) is assigned, vJailbreak creates the target VM with the following server metadata:

Metadata key	Value
HOTPLUG_CPU	Source VM’s current vCPU count
HOTPLUG_MEMORY	Source VM’s current memory (MB)
HOTPLUG_CPU_MAX	2x the source VM’s vCPU count
HOTPLUG_MEMORY_MAX	2x the source VM’s memory (MB)

The max keys define the ceiling for post-migration live resize. They are set to twice the source VM’s size so the migrated VM has hotplug headroom out of the box — for example, a VM migrated with 2 vCPUs and 4096 MB RAM can be live-resized up to 4 vCPUs and 8192 MB RAM.

Caution

Hotplug metadata can only be set at VM creation time and cannot be modified afterward. To resize beyond the 2x ceiling, the VM must be recreated.

Note

Standard flavors without hotplug extra specs will not support live resize. The VM must be powered off for a cold resize in that case.

PCI Slot Exhaustion When Attaching Disks with virtio-blk

During conversion, vJailbreak attaches the target volumes to the vJailbreak VM (or its agent VMs). If the vJailbreak image is uploaded without a disk bus setting, OpenStack uses the default virtio-blk bus, where every attached volume consumes its own PCI slot. Migrating VMs with many disks, or running many parallel migrations on one agent, Maximum 26 devices can be attached after which PCI slots will exhaust and volume attach fails with:

libvirt.libvirtError: internal error: No more available PCI slots

Workaround: Set the disk bus to virtio-scsi on the vJailbreak image before creating the vJailbreak VM. All attached volumes then share a single SCSI controller (one PCI slot, up to 256 devices):

openstack image set \
  --property hw_disk_bus=scsi \
  --property hw_scsi_model=virtio-scsi \
  <vjailbreak-image-name-or-ID>

Note

The disk bus is fixed when the VM is created. If the vJailbreak VM is already deployed, recreate it from the updated image. Agent VMs created during scale up use the same image, so set these properties before scaling up.

See the full troubleshooting entry: Disk attach fails during migration: No more available PCI slots.

Low Disk Space in the Source VM

Before starting conversion, virt-v2v checks that each filesystem inside the source VM has sufficient free space. If any filesystem is too full, the conversion fails before it begins.

Minimum free space required inside the source VM (source: virt-v2v docs):

Filesystem	Minimum free space
Linux root (/)	100 MB
Linux /boot	50 MB (needed to rebuild initramfs)
Windows C: drive	100 MB (virtio drivers and guest agents are copied in)
Any other mountable filesystem	10 MB

Each filesystem must also have at least 100 free inodes.

Workaround: Before migrating, free up space inside the source VM on any full partitions. Check with df -h (Linux) or Disk Management (Windows).

Hot Migration Requires Virtual Hardware Version 7 or Newer

vJailbreak Hot migration (Copy live VMs, then power off) relies on VMware Changed Block Tracking (CBT) to copy only changed disk blocks during the live sync phase. CBT is available only on VMs running virtual hardware version 7 or newer (VMware KB 1020128).

VMs on older hardware versions (for example, version 4) do not expose the CBT property at all, so Hot migration cannot track changed blocks for them.

Symptom: A Hot migration of a legacy-hardware VM fails at the CBT step. The reported error looks similar to:

CBT is not enabled on disk <id>

What to do — choose one:

1. Use cold migration (Power off VMs, then copy) for these VMs. Cold migration copies each disk once in full while the VM is powered off and does not use CBT, so it works on any hardware version. (Recommended — requires no changes to the source VM.)
2. Upgrade the VM’s virtual hardware version to 7 or newer in vCenter, then use Hot migration if you need minimal downtime. Upgrading the hardware version requires a VM power-off and cannot be reversed — review VMware’s documentation before proceeding.

VM virtual hardware version	Hot migration	Cold migration
7 or newer	Supported	Supported
Below 7 (e.g., version 4)	Not supported — use cold migration	Supported

Note

To check a VM’s hardware version in vCenter, select the VM and look at VM Hardware → Compatibility (shown as “ESXi X.X and later (VM version N)“).

vJailbreak Accelerated Copy

The limitations below are specific to vJailbreak Accelerated Copy. See its full limitations list for the remaining constraints.

Concurrent Disk Attach Can Fail

When several migrations reach the disk-attach step at the same time on the same Proxy VM, vCenter does not always handle the simultaneous reconfigure tasks gracefully and rejects some attach requests, failing those migrations. This is a transient race condition — the migrations that attached first are unaffected and continue into the copy phase.

Workaround: Retry the failed migrations once the others have moved into the copy phase. To reduce the chance of the race, stagger migration start times or distribute migrations across additional Proxy VMs.

See Proxy VM disk attach fails when several migrations start together.

Proxy VM Must Use a PVSCSI Controller

vJailbreak matches each attached snapshot disk to a block device inside the Proxy VM by disk UUID, which works only on the VMware Paravirtual (PVSCSI) controller. The Proxy VM’s SCSI controller 0 must be PVSCSI — LSI Logic SAS, LSI Logic Parallel, and BusLogic Parallel are not supported. Migrations using any other type fail with could not identify block device for disk <uuid>.

Workaround: Power off the Proxy VM and set Edit Settings → SCSI controller 0 → Change Type → VMware Paravirtual before registering it in vJailbreak.

See Configure the SCSI Controller Type on the Proxy VM and could not identify block device.

Application Reboot During Migration

Cold migration (Power off VMs, then copy) powers off the source VM before copying its disk. The destination VM boots fresh after migration completes. Applications must tolerate a reboot — any in-memory state, open transactions, or non-persistent connections will be lost.

Hot migration (Copy live VMs, then power off) minimizes downtime but still requires a brief power-off during the final cutover phase to synchronize the last changed blocks. Applications should be tested for graceful handling of this cutover reboot.

Caution

Before migrating, verify that your application starts cleanly after a cold reboot. Applications that require manual intervention to restart (e.g., databases with crash-inconsistent state) should be cleanly shut down inside the VM before initiating cold migration.

Retrying a Failed Migration

The Retry action reopens a failed migration in the migration form so its configuration can be corrected. The following limitations apply. See Retry a Failed Migration for the full workflow.

Limitation	Detail
VMs with RDM disks cannot be retried	Shared RDM disk state prevents an automatic retry. The Retry button is disabled for these migrations and the migration must be restarted manually.
A retry always produces a single-VM plan	Retrying one VM from a plan that covered several VMs moves that VM into a plan of its own. The remaining VMs stay in the original plan and are unaffected.
Bulk retry cannot change configuration	Retry Selected restarts each migration with its existing configuration. To change settings, retry the migration individually.
Credentials and source cluster are locked	A retry cannot change the VMware or OpenStack credentials or the source cluster. Create a new migration instead.

Note

Changing the target PCD cluster during a retry clears the network and storage mappings, because mappings are specific to a cluster. Select new mappings before submitting.