Host commissioning via VCF Operations or SDDC Manager fails with Error: "Either there are missing uplinks or the given uplinks do not match with existing cluster host uplinks"

Products

• VMware SDDC Manager
• VMware Cloud Foundation

Issue/Introduction

• When attempting to commission or add a host to an existing cluster via VCF Operations or SDDC Manager, the task fails during the validation phase.
• The UI reports a compatibility mismatch between the incoming host and the existing hosts in the cluster regarding network uplink configurations.
• The VCF Operations/SDDC Manager UI displays the following error:

• Under SDDC Manager's /var/log/vmware/vcf/domainmanager/domainmanager.log below log snippets are available:

  YYYY-MM-DDTHH:MM:SS ERROR [vcf_dm,################,####] [c.v.v.h.a.h.AddHostClusterCompatibilityValidationAction,dm-exec-#]  Not all uplink names given in input spec match with ones configured on existing cluster hosts.
YYYY-MM-DDTHH:MM:SS ERROR [vcf_dm,################,####] [c.v.e.s.o.model.error.ErrorFactory,dm-exec-#]  [######] INPUT_SPEC_UPLINKS_DO_NOT_MATCH_WITH_EXISTING_CLUSTER_HOST Either there are missing uplinks or the given uplinks do not match with existing cluster host uplinks.
com.vmware.evo.sddc.orchestrator.exceptions.OrchTaskException: Either there are missing uplinks or the given uplinks do not match with existing cluster host uplinks.
        at com.vmware.vcf.hostmanager.action.header.AddHostClusterCompatibilityValidationAction.validateHostCompatibility(AddHostClusterCompatibilityValidationAction.java:111)
        at com.vmware.evo.sddc.stretchclustermanager.tasks.AddHostClusterCompatibilityValidationForStretchAction.execute(AddHostClusterCompatibilityValidationForStretchAction.java:122)

Environment

• VMware Cloud Foundation (VCF) 9.x
• SDDC Manager 5.x / 9.x
• ESXi Host 8.x / 9.x

 

Cause

This issue occurs when the Network Selection or the Uplink Mapping defined in the Host Commissioning spec (JSON or UI input) does not match the hardware or logical configuration of the existing hosts within the target cluster.

Resolution

To resolve this, you must ensure the networking metadata for the new host perfectly aligns with the established cluster members.

Step 1: Identify Existing Cluster Configuration:

1. Log into the vSphere UI and navigate to the existing cluster.
2. Navigate to Hosts and Clusters > Select an existing host in the cluster.
3. Navigate to Configure > Networking > Virtual switches.
4. Note the number of uplinks and their exact names (e.g., uplink1, uplink2) on the vDS.

Step 2: Verify Physical NIC Mapping:

• Ensure the physical vmnic(s) on the new host are available and match the intended speed/type of the existing cluster hosts.

Step 3: Update the Commissioning Spec (JSON):

Note: If using the API or a bulk import, review the JSON file. Ensure the networkSettings block matches the cluster:\

• Uplink Names: Must be identical to the vDS uplink names.
• NIC IDs: Ensure vmnicX assignments are correct for the hardware.

Step 4: Retry the Task:

Note: If the host was partially commissioned, decommission the host to clear the stale entry. For more information, refer Decommission Hosts

1. Re-run the commissioning process with the corrected uplink mapping.
2. Proceed with the Add Host task in SDDC Manager.

Additional Information

VCF requires homogeneous networking configurations across all hosts in a cluster. The failure is specifically triggered when:

1. The number of vmnics assigned to uplinks on the new host differs from the existing hosts.
2. The names of the uplinks (e.g., uplink1, uplink2) provided in the input spec do not match the Distributed Switch (VDS) uplink names used by the cluster.
3. The physical vmnic identifiers (e.g., vmnic0, vmnic1) are mapped incorrectly compared to the cluster standard.