ESXi vmnic numbering and vSwitch mapping jumbled after adding new network adapters

Products

• VMware vSphere ESXi

Issue/Introduction

• After adding new physical NICs (vNICs or physical adapters) to an ESXi host, the existing vmnic numbering changes (e.g., vmnic0 becomes vmnic2).
• This causes a mismatch with existing vSwitch and port group configurations, leading to network connectivity loss as the logical vSwitch is no longer mapped to the correct physical port.
• No specific error message is generated; however, the esxcfg-nics -l output shows a different vmnic-to-MAC address correlation than what was previously configured.

Environment

• VMware ESXi
• Cisco UCS, HPE Synergy, or other blade environments with high vNIC density

Cause

ESXi uses a deterministic algorithm to map PCI functions to logical aliases. When hardware is added, the device manager may assign the first available unassigned alias to a new port. If the firmware presents devices in a different order (e.g., during a motherboard replacement or BIOS-to-UEFI switch), the previous persistent mappings may be superseded.

Resolution

To restore and persist VMNIC numbering, you must manually assign (alias) the VMNIC name to the specific PCI address of the adapter.

1. Identify Current Mappings: Log in to the ESXi shell via SSH and identify the MAC addresses and current VMNIC names:
   • esxcfg-nics -l
2. Retrieve PCI Bus Addresses: List the internal device aliases to find the PCI bus address for each NIC:
   • localcli --plugin-dir /usr/lib/vmware/esxcli/int/ deviceInternal alias list
3. Manually Store Aliases: Assign the desired vmnicN name to the corresponding PCI bus address. Repeat this for each NIC that needs to be re-ordered.

   Note: If the NIC uses a native driver, you must update both the pci and logical bus types.

   Example (Setting vmnic0 to address s00000002.00):

   • localcli --plugin-dir /usr/lib/vmware/esxcli/int/ deviceInternal alias store --bus-type pci --alias vmnic0 --bus-address s00000002.00
   • localcli --plugin-dir /usr/lib/vmware/esxcli/int/ deviceInternal alias store --bus-type logical --alias vmnic0 --bus-address "pci#s00000002.00#0"
4. Reboot: Reboot the ESXi host for the alias changes to take effect.
   • reboot

Verify: After the reboot, confirm the VMNIC order matches your vSwitch configuration using esxcfg-nics -l.

 

Workaround

1. If manual re-aliasing is not feasible across a large environment, migrating to a vSphere Distributed Switch (VDS) is recommended, as it manages networking configuration at the vCenter level rather than relying on local host VMNIC numbering consistency.
2. If this is not possible, another workaround is to use Host profiles to automate the fix.

 

Additional Information

Reference KB: 

How VMware ESXi determines the order in which network device names are assigned to the devices