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

Cause

• Starting in ESXi 5.5, the device manager uses a deterministic algorithm to assign aliases based on PCI bus scanning.
• While this is typically stable, the introduction of new hardware can alter the discovery order on the PCI bus.
• Because the VMNIC alias is mapped to the PCI address, adding a new card may cause the "next available" alias to be assigned to a new port, or shift the sequence if the hardware firmware presents ports in a new order during the boot process.

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

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.

Additional Information

Reference KB: 

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