HCX migration failure with the error IPv6 to IPv4 address family mismatch

Products

• VMware HCX

Issue/Introduction

• When attempting to perform VMware HCX vMotion migrations, the process fails with an "address family mismatch" error.
• This occurs when an ESXi host, configured with both IPv4 and IPv6 management interfaces (especially with IPv6 preferred), tries to establish a vMotion communication with the HCX Mobility Agent (MA), which currently only supports IPv4.
• Log lines similar to the below are encountered on the HCX Manager in /common/logs/admin/app.log

  <Time stamp> UTC [VmotionService_SvcThread-3203, Ent: HybridityAdmin, , TxId: ########-####-####-####-############] ERROR c.v.h.s.v.j.StartSourceSideRelocateVmWorkflow- [########-####-####-####-############] Error while executing startSourceSideRelocateVmWorkflow state 'WAIT_FOR_RELOCATE_INITIAL_PROGRESS'.
  java.lang.RuntimeException: Unable to prepare migration. msg.migrate.prepare.failed:Unable to prepare migration. msg.migrate.addr.mismatch:Network addresses '####:####:####:####::##' and '###.###.###.###' are from different address families.
  

Environment

VMware HCX
VMware ESXi 7.x 

Cause

This is a known issue/limitation in older versions of ESXi (vSphere 7.x and earlier) where the ESXi host may prioritize or default to using its IPv6 address for vMotion communication, even when an IPv4 address is also available.
Since the HCX Mobility Agent (MA) host does not support IPv6 for vMotion operations, this leads to an incompatible IP address family mismatch and the subsequent migration failure.

Resolution

This issue is resolved in VMware vSphere 8.0u3, available at Broadcom downloads.

If you are having difficulty finding and downloading software, please review the Download Broadcom products and software KB.

Workaround:
You can apply the following:

1. Remove the affected ESXi host from the vCenter inventory.
2. Add the ESXi host back to vCenter, but ensure you explicitly use its IPv4 address (e.g., ###.###.###.###) in the "Host name" field during the re-addition process. Do not use its hostname or IPv6 address.
3. Perform a test HCX vMotion from this re-added host to verify if the migration now proceeds successfully.

Additional Information

This applies to HCX cross-site vMotion and RAV when the MA host is used.
This may not apply to HCX Assisted vMotion (HAV) if the target ESX host also supports IPv6.