Issue/Introduction

"The platform shows VMTools as not installed" is a symptom category, not a single root cause. This article is a routing guide: it collects differentiating evidence and directs the investigation. Do not classify the issue as a driver problem or product bug based only on the platform status.

Symptoms

• The VMTools/GuestTools directory or service is present in Windows, but the platform still shows "not installed."
• QGA might be unreachable, the version might be empty, a stale installation-failed tag might remain, or a Defender quarantine event might be present.
• The key differentiators are whether VirtIO Serial works, whether the services are running, whether VERSION is valid, and whether security software quarantined files.

Environment

A Windows guest where VMTools installation was run, but the platform status remains not installed, installation failed, or shows an incorrect version.

Possible causes

Check in this order: device driver, service/process, version file, security software, and platform status refresh. Eliminate explicit in-guest failures before determining whether only the control-plane status has not refreshed.

Issue classification

• Type: Symptom navigation/evidence routing. This article does not directly classify the root cause.
• Known issue: Not unique. See TIC-6202/TIC-5001 for driver issues, TIC-5977 for VERSION issues, TIC-3099 for status refresh, TIC-5236/ZSTAC-81243 for stale failure tags, and ZSV-12861 for Defender quarantine.
• Verified version: TIC-6202 applies to ZSphere 4.10.25. For other branches, use the version recorded in the corresponding Jira issue.
• Confidence: High only for the routing conclusion. This article does not replace a root-cause article.

Resolution

Check 1: Check the VirtIO device status

• Purpose: Verify whether the VirtIO Serial driver required by the QGA channel is abnormal.
• Read-only PowerShell:

  Get-PnpDevice | Where-Object { $_.FriendlyName -match 'VirtIO|Serial|Balloon' } |
    Format-Table Status,Class,FriendlyName,InstanceId -Auto

• If VirtIO Serial/Balloon is Error or Unknown, or Device Manager shows a yellow warning icon: Go to KB-100554.
• If all devices are OK: Continue to check services. Do not cite TIC-6202 as the root cause.

Check 2: Check services and processes

• Read-only PowerShell:

  Get-Service | Where-Object { $_.Name -match 'qemu|guest|zwatch' } |
    Format-Table Name,Status,StartType -Auto
  Get-Process | Where-Object { $_.ProcessName -match 'qemu-ga|zs-tools|zwatch' } |
    Select-Object ProcessName,Id,Path

• If the qemu-ga/GuestTools service is stopped: This is the guest-service failure branch. Collect event logs and do not attribute it directly to a driver.
• If the services are running: Continue to check the version file and Defender.

Check 3: Check installation markers and security software

• Read-only PowerShell (adjust the paths to the actual installation directory):

  Get-ChildItem 'C:\Program Files\GuestTools' -Force -ErrorAction SilentlyContinue
  Get-Content 'C:\Program Files\GuestTools\VERSION' -ErrorAction SilentlyContinue
  Get-MpThreatDetection | Select-Object InitialDetectionTime,ThreatName,Resources

• If VERSION is empty or absent: This is close to the installation-write failure in TIC-5977. Collect the installation logs.
• If Defender records quarantined zs-tools.exe: Go to KB-100562. ZSV-12861 was Open as of 2026-08-13 and must be escalated.
• If files and services are normal and there is no quarantine: Check platform audit records and the status update time. This might be the non-real-time refresh branch in TIC-3099 or a stale GuestTools::InstallFailed tag; platform-side manual confirmation is required.

Recommended actions

Follow the branch identified by the evidence. Driver updates, restoring quarantined files, restarting services, refreshing platform status, and clearing tags all require manual approval. Do not repeatedly reinstall VMTools before identifying a branch.

Long-term solution

The platform should distinguish among "driver/channel failure," "service not running," "version unknown," "security software quarantine," and "status refresh pending" instead of showing all of them as "not installed."

Additional information

When to escalate

• All guest checks are normal, but the page continues to show not installed.
• Defender detected or quarantined VMTools files.
• A driver update, guest restart, tag cleanup, or platform status refresh is required.
• The issue occurs intermittently on Windows 2012 and disappears after restart without supporting evidence: Refer to ZSV-9951 (Open) and do not determine the root cause independently.

Information to collect

ZSphere/Windows versions, VMTools version, Device Manager screenshot, output of the commands above, installation logs, Windows System/Defender events, platform audit timestamp, and VM UUID (redact it when submitting a ticket).

Related issues

• TIC-6202, Closed/Done.
• TIC-5977, Closed/Done.
• TIC-3099, Closed/Done.
• ZSTAC-81243, Closed/Fixed and verified on Cloud 5.5.28; do not apply it directly to ZSphere.
• ZSV-12861, Open.
• ZSV-9951, Open; root cause unconfirmed.
• Status verified on 2026-08-06.