VMware Tools is a critical component that enhances the performance and manageability of virtual machines running on VMware platforms. Administrators will keep VMware tools up to date to ensure optimal disk performance, network connectivity, and guest OS management.
However, when updating VMware Tools, administrators sometimes encounter the “VMware Tools Error 21009” (or VIX Error Code=21009), which typically appears during installation or upgrade of VMware Tools within a VM.
In this guide, we’ll explain what the error means, why it occurs, and how to fix it step by step.
What Is VMware Tools Error 21009?
Error 21009 (often displayed as VIX Error Code 21009) is a failure that occurs during the installation or upgrade of VMware Tools inside a virtual machine running on VMware virtualization platforms.
The error typically occurs when the VMware Tools installer cannot complete execution in the guest operating system. As a result, the installation process stops and the Tools upgrade fails, leaving the virtual machine without the latest drivers and integration services.
Typical Error Message
Administrators usually see one of the following messages during a VMware Tools upgrade:
- “Error upgrading VMware Tools. VIX error code = 21009.”
- “VMware Tools installation failed.”
- “Unable to update VMware Tools inside the guest operating system.”
These messages may appear when initiating an upgrade from vSphere Client, during automated lifecycle updates, or while running the installer manually inside the guest OS.
When the Error Usually Occurs
In most environments, VMware Tools error 21009 appears in the following situations:
- During automatic VMware Tools upgrades initiated from vCenter or ESXi
- When installing VMware Tools manually inside a Windows virtual machine
- After upgrading an ESXi host, which triggers a VMware Tools version mismatch
- During VM provisioning or template deployment, when VMware Tools is installed automatically
Although the error may appear serious, it usually indicates that the installer encountered a missing dependency, a permission issue, or a leftover installation file. Once the underlying issue is identified, the VMware Tools upgrade can typically be completed without affecting the virtual machine itself.
Why VMware tools vix error 21009 Happens?
In most cases, error 21009 is caused by issues that disrupt the VMware Tools upgrade file transfer, installation, or permission workflow, most of which are avoidable with basic maintenance.
Below are the most common reasons why this error occurs when installing or upgrading VMware Tools.
1. Stale/Residual Upgrade Files (Most Common)
The most common reason is leftover files from previous VMware Tools upgrades that lock or block new installation binaries. When the upgrade process runs (auto or manual), it can’t overwrite or rename these stale files, leading to a file copy failure (marked by HgfsStatus = 8 in the VM’s vmware.log).
- For Windows VMs: A locked VMwareToolsUpgrader.exe file in C:\Windows\Temp\vmware-SYSTEM\ (from a failed or incomplete prior upgrade).
- For RHEL/CentOS Linux VMs: A stale /tmp/vmware-root folder that persists after a previous upgrade, preventing new files from being written.
These residual files often remain due to interrupted upgrades (e.g., VM reboot mid-upgrade) or incomplete cleanup by the VMware Tools installer.
2. Missing vmware-SYSTEM Folder (Windows Only)
Windows VMs rely on the “vmware-SYSTEM” folder to store upgrade binaries during the installation process. If this folder is missing, the installer cannot copy critical files to the guest OS and cause the problem.
3. Failed Volume Shadow Copy (VSS) Service (Windows VMs)
The Volume Shadow Copy Service (VSS) is required for the VMware Tools installer to write files to the Windows guest OS. If VSS is stopped, corrupted, or misconfigured, the upgrade process cannot complete file transfers. This is often accompanied by VSS-related errors in the Windows Event Log.
4. Security Restrictions (Disabled Guest-Initiated Upgrades)
VMware’s default security configuration sometimes blocks guest OS-initiated VMware Tools upgrades, which can trigger error 21009. This happens when the VM’s .vmx configuration file has the setting:
isolation.tools.guestInitiatedUpgrade.disable = TRUE
This restriction prevents the guest OS from initiating the upgrade, even if triggered manually or via vCenter.
5. Corrupted/Unmountable VMware Tools ISO (ESXi Host Side)
This condition is rare but confirmed in community reports. If the VMware Tools ISO file (windows.iso for Windows VMs, linux.iso for Linux VMs) on the ESXi host is corrupted or cannot be mounted, the upgrade process will fail to access the necessary binaries.
The ISO files are stored in /usr/lib/vmware/isoimages/ on ESXi hosts—permissions issues or file corruption here can lead to error 21009.
How to Fix VMware Tools Error 21009 Step by Step
Before performing major repairs, such as reinstalling VMware Tools, backing up VMware VMs with i2Backup is essential to avoid data loss or system corruption.
i2Backup is a robust, enterprise-grade backup solution for VMware vSphere environments and other vitalization, databases, servers, etc. It supports reliable, application-consistent backup and recovery for critical data with flexible scheduling, fast restore, and centralized management.
Now, just follow the troubleshooting steps below to solve the problem.
Fix 1. Reboot the affected VM
When encountering a VMware issue, restarting the VM is always worth trying. A quick reboot clears stale file locks, resets the VMware Tools service, and resolves temporary OS glitches.
Fix 2. Restart the VSS service (Windows only):
If the VSS service is stopped, it disrupts file transfers during the upgrade. Open an elevated Command Prompt and run:
net start vss
If the service fails to start, check the Windows Event Log for VSS-related errors (e.g., corrupted shadow copies) and resolve those first.
Fix 3. Manually upgrade VMware Tools from Guest OS
Bypass auto-upgrade file copy issues by downloading the latest VMware Tools installer directly from the guest OS (via VMware’s official site) and running it manually. This skips the ESXi-hosted ISO mount and temporary file transfer steps that often trigger the error.
Fix 4. Remove Stale VMware Installation Files
Old or corrupted installer files from previous upgrades can block a new upgrade attempt. To solve the 21009 error, just delete these files. Here are the steps.
► For Windows VMs
Step 1. Log in to the Windows VM as an administrator.
Step 2. Open an elevated Command Prompt.
Step 3. Run the following command to remove the read-only lock from the stale upgrade file:
attrib -R C:\Windows\Temp\vmware-SYSTEM\VMwareToolsUpgrader.exe
Step 4. Reboot the VM and start the VMware Tools upgrade again.
Cleaning these files allows the installer to extract fresh components during the next installation attempt.
►For RHEL/CentOS/Ubuntu Linux VMs
Step 1. Log in to the Linux VM as root (or use sudo for elevated privileges).
Step 2. Open a terminal and run the command to delete the stale /tmp/vmware-root folder:
rm -rf /tmp/vmware-root
Step 3. Retry the VMware Tools upgrade (via vCenter or vmware-install.pl script in the guest OS).
Fix 5. Restore the Missing VMware-SYSSTEM Folder (Windows Only)
If the C:\Windows\Temp\vmware-SYSTEM folder is missing, it can cause HgfsStatus = 1 in logs. We provide two methods to restore the folder. Use one of these two methods to restore it
►Method A: Recreate the Folder via VMware Tools Service (No VM Reboot)
Step 1. Open an elevated Command Prompt.
Step 2. Stop the VMware Tools service:
sc stop vmtools
Step 3. Start the VMware Tools service (this auto-recreates the vmware-SYSTEM folder):
sc start vmtools
Step 4. Verify the folder exists at C:\Windows\Temp\vmware-SYSTEM, then retry the upgrade.
► Method B: ESXi Host-Side Fast Suspend Resume (FSR)
If Method A fails, use ESXi’s FSR feature to reset the VM’s host-guest integration and the vmware-SYSTEM folder will be recreated.
Step 1. SSH into your ESXi host (enable SSH first if disabled via ESXi WebUI).
Step 2. List all VMs to get the ID of the affected VM:
vim-cmd vmsvc/getallvms
Step 3. Run the FSR command for the affected VM (replace <VM-ID> with the actual VM ID):
vim-cmd vmsvc/power.suspendResume <VM-ID>
Step 4. After FSR completes, check if the vmware-SYSTEM folder is restored, then retry the upgrade.
Fix 6. Install or Repair Microsoft Visual C++ Redistributables
The installer for VMware Tools relies on several Microsoft Visual C++ runtime components. If these libraries are missing or corrupted, especially if your upgrade logs show errors like “vc_runtimeMinimum_x86.msi missing” or “Visual C++ Redistributable installation failed” alongside error 21009, you can follow the steps below to install or repair Microsoft Visual C++ Redistributables and solve the problem.
Step 1. Open Control Panel > “Programs and Features” in the Windows virtual machine.
Step 2. Look for installed Microsoft Visual C++ Redistributable packages. If they are missing, download and install the latest versions from Microsoft.
Step 3. If they already exist, right-click on each and select “change” > “Repair” to fix potential corruption.
Step 4. Restart the virtual machine and retry the VMware Tools upgrade.
Fix 7. Check and Fix VMware Tools Repository Permission
Incorrect permissions on the VMware Tools repository directory or ISO files on the ESXi host often block ISO access and cause the error 21009 even if the ISO itself is intact. So verify and correct host-side permissions to ensure the ESXi host can access and serve the VMware Tools ISO files.
Step 1. Enable SSH access to the ESXi host. Connect to the host using an SSH client.
Step 2. Run the command to verify the directory access rights:
ls -ld /usr/lib/vmware/isoimages/.
The correct permissions should be `rwxr-xr-x` (owned by root, group root). This ensures the ESXi host can read and access the ISO files stored in this directory.
Step 3. If the permissions do not match `rwxr-xr-x`, run the command to adjust them:
chmod 755 /usr/lib/vmware/isoimages/
This grants the necessary read, write, and execute permissions to the root user, and read/execute permissions to other users—critical for ISO access.
Step 4. Run the command to check the permissions of the VMware Tools ISO files:
ls -l /usr/lib/vmware/isoimages/.
Locate the appropriate ISO for your guest OS (Windows: `windows.iso`; Linux: `linux.iso`). The correct permissions for these ISO files should also be `rwxr-xr-x` (owned by root, group root).
Step 5. If the ISO file permissions are wrong, run the command to correct them (replace `windows.iso` with `linux.iso` for Linux VMs): chmod 755 /usr/lib/vmware/isoimages/windows.iso. This ensures the ESXi host can mount the ISO file to the guest VM.
Once permissions are corrected, proceed to the next fix if error 21009 persists—this confirms the host can access the ISO repository, and the issue likely lies with ISO mounting or corruption.
Fix 8. Fix ESXi Host ISO Mount/Corruption Issues
If the error stems from a corrupted or unmountable VMware Tools ISO on the ESXi host, resolve it with these steps:
Step 1. Power on the affected VM and open its settings (vCenter → VM → Edit Settings).
Step 2. Under “CD/DVD Drive 1”, select “Datastore ISO File” and browse to the correct ISO:
- For Windows VMs: windows.iso (stored at /usr/lib/vmware/isoimages/ on ESXi)
- For Linux VMs: linux.iso (same directory)
Step 3. Check “Connect at power on” and click “OK” to mount the ISO.
Step 4. Inside the guest OS, open the mounted ISO and run the VMware Tools installer manually to solve auto-ISO mount failures.
Step 5. If the ISO fails to mount, SSH into the ESXi host and run:
md5sum /usr/lib/vmware/isoimages/windows.iso (or `linux.iso`).
Compare the output to the official MD5 checksum from VMware’s website—if they do not match, the ISO is corrupted and needs to be replaced (download the latest ISO from VMware and replace the existing file in the repository directory).
Step 6. Inside the guest OS (Windows or Linux), open the mounted ISO drive (a virtual CD/DVD drive) and run the VMware Tools installer directly.
This bypasses the auto-upgrade’s file transfer mechanism (a common source of error 21009) and lets you install the tools directly from the mounted ISO.
Fix 9. Resolve Security Restriction Issues
If error 21009 is caused by disabled guest-initiated upgrades (via VM configuration), follow these steps to adjust the setting:
Step 1. Navigate to the affected VM’s datastore (via vCenter or ESXi WebUI).
Step 2. Locate the VM’s .vmx configuration file and “create a backup copy” (critical—prevents configuration loss).
Step 3. Download the .vmx file to your local machine and open it in a text editor (e.g., Notepad, VS Code).
Step 4. Find the line isolation.tools.guestInitiatedUpgrade.disable = TRUE (if missing, add it).
Step 5. Change the value to FALSE:
isolation.tools.guestInitiatedUpgrade.disable = "FALSE"
Step 6. Save the file, upload it back to the datastore, and overwrite the original (ensure the VM is powered off first for safety).
Step 7. Power on the VM and retry the VMware Tools upgrade.
Fix 10. Perform a Clean VMware Tools Reinstallation
If all previous fixes fail to resolve VMware Tools error 21009 when updating, a clean reinstallation of VMware Tools is the most reliable final solution.
This process removes corrupted services, leftover files, conflicting registry entries, and outdated drivers that standard troubleshooting may miss—effectively resetting the VMware Tools configuration to a fresh state.
►For Windows VMs
Step 1. Log in to the Windows VM as an administrator.
Step 2. Open Control Panel → Programs → Uninstall a Program.
Step 3. Locate “VMware Tools” in the list, right-click it, and select “Uninstall”.
Step 4. Follow the uninstall wizard prompts, then restart the VM when prompted (critical for removing all residual files).
Step 5. After the VM reboots, delete any remaining VMware-related residual folders:
- `C:\Windows\Temp\vmware-SYSTEM`
- `C:\Program Files\VMware\VMware Tools`
Step 6. Mount the VMware Tools ISO from the ESXi host or download the latest VMware Tools installer from the official VMware website.
Step 7. Run the installer as an administrator and follow the wizard to complete a fresh installation.
Step 8. Restart the VM one final time and verify the upgrade completes without error 21009.
►For RHEL/CentOS/Ubuntu Linux VMs
Step 1. Log into the Linux VM as root (or use `sudo` for elevated privileges).
Step 2. Open a terminal and run the uninstall command for VMware Tools: vmware-uninstall.pl (if the script is available) or use your package manager (e.g., `yum remove open-vm-tools` for RHEL/CentOS, `apt remove open-vm-tools` for Ubuntu).
Step 3. Delete residual folders: rm -rf /tmp/vmware-root and rm -rf /etc/vmware-tools.
Step 4. Restart the VM:
reboot
Step 5. After the VM reboots, mount the VMware Tools ISO from the ESXi host (Fix 5, Step 2–3) or install the latest version via your package manager (e.g., `yum install open-vm-tools`).
Step 6. Verify the installation completes successfully and retry the upgrade if needed.
Tip: Bulk Fix for Multiple VMs (PowerCLI Automation)
For administrators managing large numbers of virtual machines, manually applying the fixes above to every VM is inefficient.
In enterprise environments, VMware PowerCLI can be used to automate the most common repairs in bulk—including removing stale temporary files, restarting the VMware Tools service, and deleting leftover folders across many Windows or Linux VMs at once. This lets you resolve error 21009 at scale without repeating the same steps on each machine individually.
You only need to run basic, targeted commands through PowerCLI to replicate the core fixes covered earlier, making it ideal for vSphere environments with dozens or hundreds of affected VMs.
Prevent VMware Tools Error 21009 After Fixing
You can greatly reduce or fully avoid the VMware error by applying these simple, long-term best practices across your vSphere environment.
1. Regularly clean up stale VMware temporary files on Windows and Linux VMs to avoid locked installation files.
2. Exclude C:\Windows\Temp\vmware-SYSTEM (Windows) and /tmp/vmware-root (Linux) from system cleanup tools or group policies.
3. Keep your VMware up-to-date, as Broadcom regularly resolves VMware Tools upgrade-related bugs.
4. Monitor the Volume Shadow Copy (VSS) service on Windows VMs to ensure it runs reliably during upgrades.
5. Use standardized VM templates with correct VMware Tools settings to avoid permission or configuration issues.
6. Never interrupt VMware Tools installation or upgrade processes, as this is a common cause of residual broken files.
FAQs About VMware Tools
1. How to check if VMware Tools are up to date
Locate the VMware Tools icon in the System Tray. Move the mouse pointer over the icon. The message VMware Tools can be updated. displays, the VMware Tools installation is out of date.
2. What happens if VMware tools are out of date?
Outdated VMware Tools cause poor VM performance (disk/network lag), broken host-guest integration (e.g., copy-paste, screen resizing), and compatibility issues with new ESXi versions. It also increases the risk of upgrade errors like 21009 and limits access to VMware’s advanced VM management features.
3. How to install the latest version of VMware Tools?
- Via vCenter/ESXi WebUI: Select the powered-on VM > Right-click > Guest OS > Install/Upgrade VMware Tools > Follow the on-screen wizard to complete installation/upgrade.
- Manual ISO Mount: In VM settings, mount the ESXi host’s official VMware Tools ISO (Windows: windows.iso; Linux: linux.iso), then run the installer in the guest OS (Windows: setup.exe; Linux: vmware-install.pl or package manager).
4. Can you upgrade VMware tools without rebooting?
Most upgrades support non-reboot installation for Windows and Linux VMs, available via vCenter/ESXi. However, major upgrades (e.g., new drivers, kernel modules) still require a VM reboot to apply changes—vCenter will prompt if a reboot is needed post-upgrade.
Conclusion
VMware Tools Error 21009 (vix error code = 21009) is a common vSphere upgrade failure, primarily caused by stale temporary files, missing the vmware-SYSTEM/vmware-root folders, VSS service failures, or corrupted Tools components.
This guide provides a prioritized workflow: start with quick workarounds, apply OS-specific fixes, and use a clean VMware Tools reinstallation as the final reliable solution. For large environments, PowerCLI automation simplifies bulk remediation.
To prevent recurrence, follow best practices and always back up VMs before major repairs. i2Backup offers enterprise-grade VMware protection with agentless backup via VADP, CBT incremental backups, and immutable storage for ransomware resilience, ensuring your infrastructure remains stable during troubleshooting and daily operations.