VCF 9.1 Convergence Failure - NullPointerException in DomainDiscoveryVdsHelper

Products

• VMware NSX

Issue/Introduction

When attempting to converge an existing vSphere/NSX environment to VCF 9.1 using the VCF Installer, the workflow fails during the Domain Discovery phase with the following error in the UI:

Failed to discovery domain inventory with vCenter [VC_FQDN]. Reference Token: [TOKEN]

In /var/log/vmware/vcf/domainmanager/domainmanager.log, a java.lang.NullPointerException is observed at DomainDiscoveryVdsHelper.getPortGroupActiveUplinks:

ERROR [vcf_dm] [c.v.v.d.u.DomainDiscoveryVdsHelper] Failed to process VDS [VDS_NAME] in vCenter [VC_FQDN]java.lang.NullPointerException: null at com.vmware.vcf.discovery.utils.DomainDiscoveryVdsHelper.getPortGroupActiveUplinks(DomainDiscoveryVdsHelper.java:464)

Environment

VCF 9.1

Cause

This issue occurs when the VCF discovery automation encounters a Distributed Portgroup (DVPortgroup) that has an empty or unset Active Uplinks list in its Teaming and Failover policy. The discovery logic expects at least one active uplink to be defined and fails with a null reference when it attempts to iterate over an unpopulated activeUplinkPort array.

This commonly affects NSX-managed VLAN-backed segments that were created without an explicit uplink teaming policy.

Resolution

To resolve this issue, manually assign an active uplink to the affected portgroup in vCenter or NSX Manager.

Option 1: vCenter UI (Recommended for quick fix)

1. Log in to the vSphere Client.
2. Navigate to Networking and select the Distributed Virtual Switch (VDS) mentioned in the logs.
3. Locate the failing portgroup (identified in the domainmanager.log debug lines immediately preceding the error).
4. Select the portgroup and navigate to Configure > Settings > Policies.
5. Click Edit and select Teaming and failover.
6. Move at least one available uplink (e.g., Uplink 1) from the Unused or Standby list to the Active adapters list.
7. Click OK.

Option 2: NSX Manager (For VLAN-backed Segments)

1. Log in to NSX Manager.
2. Navigate to Networking > Segments.
3. Edit the affected segment and expand Advanced Configuration.
4. Ensure an Uplink Teaming Policy is selected that maps to a valid active uplink in the Transport Zone.
5. Save the configuration.

Verification

1. Access the vCenter Managed Object Browser (MOB): https://[VC_FQDN]/mob/?moid=[PORTGROUP_MOID]&doPath=config.defaultPortConfig.uplinkTeamingPolicy.uplinkPortOrder
2. Confirm that activeUplinkPort is no longer empty.
3. Retry the convergence workflow from the VCF Installer UI.