How to Resolve Proxmox Guest Tools Issues (code 1974, 1975, 1976)

This article provides guidance for diagnosing and resolving common issues related to the QEMU Guest Agent in Proxmox virtual machines. These issues may prevent successful backups, guest communication, or proper VM state reporting.

One or more of the following info messages can be reported:

• (Code 1974) QEMU Guest Agent not installed on specific VMs (ProxmoxGuestToolsNotInstalledException)

• (Code 1975) QEMU Guest Agent not running or misconfigured on specific VMs (ProxmoxGuestToolsNotWorkingOrMisconfiguredException)

• (Code 1976) VSS is not configured for Proxmox backup (Windows only)
  (ProxmoxGuestToolsVssNotBtCopyConfiguredException)

Summary of Causes and Resolutions

Error	Root Cause	Solution
NotInstalled	QEMU Guest Agent not installed	Install Guest Agent
NotWorkingOrMisconfigured	QEMU Agent not running or misconfigured	Restart/reinstall Agent
VssNotBtCopyConfigured	VSS not configured (Windows)	Configure VSS correctly

QEMU Guest Agent not installed on specific VMs (Code 1974)

Backup on specific VM is inconsistent and the some restore operations may fail. List of these affected VMs is reported.

Cause

The QEMU Guest Agent is not installed inside the specified virtual machines.

Solutions

1. Install QEMU Guest Agent

Linux:

apt install qemu-guest-agent

systemctl enable qemu-guest-agent

systemctl start qemu-guest-agent

Windows:

• Mount the VirtIO ISO in the VM

• Install QEMU Guest Agent

• Ensure the QEMU Guest Agent service is running

2. Enable Guest Agent in Proxmox

• Navigate to: VM → Options → QEMU Guest Agent → Enable

Or via CLI:

qm set <vmid> --agent enabled=1

3. Verify Installation

Run the following command on the Proxmox host:

qm agent <vmid> ping

Expected result:

{}

Result

Once installed and enabled, the uest agent should function correctly and backup operations should complete successfully.

QEMU Guest Agent not running or misconfigured on specific VMs (Code 1975)

Backup on specific VM is inconsistent and the some restore operations may fail. List of these affected VMs is reported.

Cause

The QEMU Guest Agent is installed but not functioning correctly on specific VMs due to misconfiguration or service issues.

Solution

To verify that the QEMU Guest Agent is working correctly on a Proxmox Windows VM, you need to check both the guest-side service and host-side communication. Below are detailed steps.

1. Verify via Proxmox Web Interface

The simplest way to check the agent's status is directly in the Proxmox web interface.

• Select your Windows VM from the left panel.
• Look at the Summary page for the VM. If the guest agent is running and communicating properly, you will see the VM's IP address(es) displayed in the summary panel . If no IP is shown, it often indicates a problem with the agent.

2. Verify Inside the Windows Guest*

First, ensure the service is running within Windows itself.

1. Using PowerShell (as Administrator): Run the following command to check the status of the QEMU Guest Agent service. The status should be Running.

   Get-Service QEMU-GA

2. Using the Services Console: Press Windows Key + R, type services.msc, and press Enter. Look for the service named "QEMU Guest Agent" and verify its status is "Running" and the startup type is "Automatic" .

3. Checking from the Proxmox Host

The most definitive test is to use the qm command-line tool on your Proxmox server. This checks if the host can successfully ping the agent inside the VM.

1. Connect to your Proxmox host via SSH or open the shell via the web interface.

2. Run the following command, replacing <VMID> with the actual ID number of your Windows VM :

   qm agent \<VMID\> ping
   

3. Interpret the result:

   • Success: If the agent is working, the command will return with no output and no error message .
   • Failure: If the agent is not responding, you will typically see an error like QEMU guest agent is not running .

Troubleshooting Common Issues

If your checks fail, here are the most common causes and solutions based on Proxmox forum discussions:

• Missing Driver: The most frequent issue on Windows is that the vioserial driver is not installed. In the Windows Device Manager, look for a device called "PCI Simple Communications Controller" with a yellow exclamation mark. You must install this driver from the attached VirtIO ISO .
• Service Not Running or Set to Automatic: Even if installed, the service might not have started. Use the steps above to start it manually and ensure its startup type is "Automatic" .
• Agent Not Enabled in VM Options: Verify that the "QEMU Guest Agent" option is enabled in the VM's Options panel in the Proxmox GUI. If you just enabled it, the VM must be fully shut down and started again (not just rebooted) for the change to take effect .
• Re-enabling the Agent: Some users have reported that toggling the agent off and on again in the VM options, followed by a full restart of the VM, can resolve the issue .
• VirtIO Driver Version: In rare cases, specific combinations of Windows versions and VirtIO driver versions can cause problems. For example, one user reported issues with version 0.1.262 on Windows 11 23H2, which were resolved by updating the guest OS or changing the driver version .

By following these steps, you can accurately diagnose whether the guest agent is running and take the necessary steps to fix it.

(Code 1976) VSS is not configured for Proxmox backup (Windows only)

Cause

The Volume Shadow Copy Service (VSS) is not configured correctly for Proxmox backups. Configure VSS correctly for MS SQL and Exchange backup plans and run them again. The rest of backup plans can work normally.

Solution

Verify the Current Value: Open the Registry Editor (regedit) on your Windows VM and navigate to the key path (HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\QEMU Guest Agent VSS Provider). Check the current numerical data for the VssOption value.

Set to VSS_BT_COPY (Value 5): To prevent the Proxmox host backups from interfering with any backup software running inside your Windows guest, you should set this value to 5.

• Right-click on VssOption and select Modify.
• In the "Value data" field, change the number to 5.
• Ensure the "Base" is set to Decimal.
• Click OK.

If the VssOption value does not exist, you can create it by right-clicking in the right pane, selecting New > DWORD (32-bit) Value, naming it VssOption, and then setting its value to 5.

Reboot the VM: For the change to take effect, you shouls fully reboot your Windows VM.

Reboot the VM: For the change to take effect, you must fully reboot your Windows VM .

Fallback Behavior: It's important to note that if the VssOption value does not exist or is set to an invalid number, the QEMU Guest Agent will default to VSS_BT_FULL (value 1)

Situation

Cause