ESXi patching is failing with ERROR: KeyError: 'VMware_locker

Products

VMware vSphere ESXi 7.0

Issue/Introduction

ESXi Patching Fails During Staging with [KeyError]

[KeyError]
'VMware_locker_tools-light_12.4.0.23259341-23259329'
Please refer to the log file for more details.

On the ESXi host: /var/run/log/esxupdate.log

<timestamp>:25Z esxupdate: 2130439: root: ERROR: Traceback (most recent call last):
<timestamp>:25Z esxupdate: 2130439: root: ERROR:   File "/usr/lib/vmware/esxcli-software", line 772, in <module>
<timestamp>:25Z esxupdate: 2130439: root: ERROR:     main()
<timestamp>:25Z esxupdate: 2130439: root: ERROR:   File "/usr/lib/vmware/esxcli-software", line 763, in main
<timestamp>:25Z esxupdate: 2130439: root: ERROR:     ret = CMDTABLE[command](options)
<timestamp>:25Z esxupdate: 2130439: root: ERROR:   File "/usr/lib/vmware/esxcli-software", line 631, in ComponentSigVerifyCmd
<timestamp>:25Z esxupdate: 2130439: root: ERROR:     res = h.GetCompSigVerifyMap(opts.rebooting)
<timestamp>:25Z esxupdate: 2130439: root: ERROR:   File "/lib64/python3.8/site-packages/vmware/esximage/HostImage.py", line 1328, in GetCompSigVerifyMap
<timestamp>:25Z esxupdate: 2130439: root: ERROR:     vibInfo = vibResult[vibId]
<timestamp>:25Z esxupdate: 2130439: root: ERROR: KeyError: 'VMware_locker_tools-light_12.4.0.23259341-23259329'

Environment

VMware vSphere ESXi

Cause

The VIB database directory on the ESXi host located at /locker/packages/var/db/locker/vibs failed to dynamically reflect updates or handle tracking records from the newer tools-light package payload. This broken references tracking inside the local repository file mappings triggers a fatal KeyError within the esxupdate utility framework.

Resolution

Perform the following technical resolution steps during an approved maintenance window. Before proceeding, ensure you place the target ESXi host into Maintenance Mode.

Method 1: Syncing Files from a Healthy Host

If you have access to a successfully upgraded host running the identical target version, you can restore missing database files:

Log in to the affected ESXi host using an SSH client.
Change your directory to the active VIB database path:
```
cd /locker/packages/var/db/locker/vibs
```
Evaluate the directory to confirm no underlying storage block corruption exists by writing a temporary test file.
Move any existing conflicting VMTools XML descriptors to a temporary backup directory.
Securely copy (scp) the clean, complete tools-light metadata files from the successfully patched host matching your target version directly into this /locker/packages/var/db/locker/vibs directory.
Re-attempt the patch update.

Method 2: Manual Descriptor Cleanup

If Method 1 is not viable or the error persists, clear out cached version locks manually:

Log in to the affected ESXi host using an SSH client.
Run the following command to check the available VMtools version:
```
esxcli software vib list | grep tools
```
Uninstall the Current VMtools VIB :
```
esxcli software vib remove --vibname=<name_of_vib>
```
(Note: If no VIB is returned, bypass any VIB removal commands and proceed directly to step 3).
Erase the existing vmtoolsRepo cache directory:
```
cd /locker/packages/
rm -rf vmtoolsRepo/
```

Perform a recursive lookup to find any stale or preserved version indicators lingering across lock paths:

ls -l -R /locker/packages

Sample output

/locker/packages/var/db/locker/addons:
total 0

/locker/packages/var/db/locker/baseimages:
total 0

/locker/packages/var/db/locker/bulletins:
total 4
-rwx------ 1 root root 737 Apr 20 2022 VMware-VM-Tools-xxxxxxxxxxxxxxxxxx.xml

/locker/packages/var/db/locker/manifests:
total 0

/locker/packages/var/db/locker/profiles:
total 0

/locker/packages/var/db/locker/reservedComponents:
total 0

/locker/packages/var/db/locker/reservedVibs:
total 0

In the above output, remove the conflicting definition file (e.g., VMware-VM-Tools-xxxxxxxxxxxxxxxxxx.xml) from the respective directory.
For example, remove the file from below directory
```
cd /locker/packages/var/db/locker/bulletins/
rm VMware-VM-Tools-xxxxxxxxxxxxxxxxxx.xml
```
Re-attempt the patch update.
After remediation, verify that the new VMtools version has been successfully installed and host is functioning as expected.