Resolving Common VSS Snapshot Failures with the VSSDiagnosticScriptOnAgent.ps1 VSS Repair Script (4380518)

Return

Feedback Submitted

Did this article solve an issue for you?

Select Rating

Title

Resolving Common VSS Snapshot Failures with the VSSDiagnosticScriptOnAgent.ps1 VSS Repair Script
Description
This article provides instructions for the VSSDiagnosticScriptOnAgent.ps1 PowerShell script. This script is a powerful troubleshooting tool designed to automatically diagnose and resolve a wide range of known issues that can cause Volume Shadow Copy Service (VSS) errors and snapshot failures on an agent machine.

Script Path:
```
C:\Program Files\AppRecovery\Agent\PowerShellScripts\VSSDiagnosticScript\VSSDiagnosticScriptOnAgent.ps1
```
Cause
Snapshot failures related to the Volume Shadow Copy Service (VSS) can be caused by a variety of underlying system issues. This script is designed to address the following common causes:
- Corruption in the NTFS file system structure.
- High fragmentation on the disk volume.
- A full System Reserved Partition (SRP) or locked/corrupted agent change logs (AALogs).
- Lingering or conflicting checkpoints (snapshots) in Hyper-V environments.
- Misconfiguration issues when running in a VMware guest OS.
- Performance degradation due to disk partition misalignment.
Resolution
The resolution is to run the VSSDiagnosticScriptOnAgent.ps1 PowerShell script, which performs several automated checks and fixes. Please review the following warnings and steps carefully before proceeding.

Important Warnings
PowerShell Execution Policy Warning

For user convenience, the script automatically attempts to run the command Set-ExecutionPolicy Unrestricted. This allows the script to run but is a broad permission change that can be a security concern in some environments.

If you prefer a more secure method that does not change the system's policies, you can first edit the script to disable this automatic change and then run the script using the per-session bypass method.

To do this:
1. Open the VSSDiagnosticScriptOnAgent.ps1 file in a text editor.
2. Find the line that says Set-ExecutionPolicy Unrestricted and add a '#' character at the beginning to comment it out (e.g., #Set-ExecutionPolicy Unrestricted). Save the file.
3. Open PowerShell as an Administrator, navigate to the script's directory, and run it with the following command:
```
powershell.exe -ExecutionPolicy Bypass -File .\\VSSDiagnosticScriptOnAgent.ps1
```
Use At Your Own Risk: This PowerShell script makes significant changes to your system. While it is designed to fix known issues, Quest does not take responsibility for any data loss, system instability, or negative consequences that may result from its use.

System Backup Recommended: It is strongly recommended that you have a complete, verified backup of your system and any critical data before running this script. You should also create a manual backup of the Windows Registry.

Actions Performed by the Script

1. Runs chkdsk to Repair NTFS Corruption

The script initiates a chkdsk command to find and fix logical file system errors or bad sectors on the disk. This is a foundational step, as file system corruption can prevent VSS from operating correctly.

Potential for System Downtime. To fix errors on a system volume, chkdsk must run before the operating system loads. The script will likely schedule this scan to run on the next reboot, which can lead to unexpected and potentially lengthy system downtime while the offline scan completes.

2. Runs defrag to Mitigate Disk Fragmentation

The script runs the disk defragmentation utility to consolidate fragmented files. On mechanical hard disk drives (HDDs), this improves I/O performance and can help VSS operations complete successfully.

Not for SSDs. This step is only beneficial for HDDs. Running a traditional defragmentation on a Solid-State Drive (SSD) provides no performance benefit and causes unnecessary write wear, which can shorten the drive's lifespan. The script may not differentiate between drive types.

3. Deletes Agent Change Logs (AALogs) to Free Space

The script identifies and deletes Rapid Recovery change logs (aalog*.* files) from the System Volume Information folder. This action is designed to free up critical space, especially on a full System Reserved Partition (SRP), which is a common cause of VSS failure.

Forces a New Base Image. This action breaks the incremental backup chain for the affected volume. The next backup will be a new, full base image, which will take significantly longer to complete and consume more storage on the Rapid Recovery Core.

4. Removes Hyper-V Checkpoints (Snapshots)

On Hyper-V hosts, the script removes checkpoints from virtual machines. This is intended to clear orphaned "Recovery" checkpoints left behind by previous failed backups, as these can interfere with new snapshot operations.

Risk of Data Loss. The script may remove all checkpoints for a VM, including legitimate, user-created checkpoints used for development or rollback purposes. This can lead to unintended data loss. It is critical to manually verify which checkpoints exist before running a script that deletes them indiscriminately.

5. Detects VMware Environment to Address VSS Provider Conflicts

The script checks if the agent is running inside a VMware VM. This is the first step in diagnosing a common issue where a VM migrated from Hyper-V retains a conflicting "Hyper-V IC Software Shadow Copy Provider". The script's purpose is to resolve this conflict, which likely involves removing the provider.

Involves Registry Modification. The actual fix for this issue requires deleting a key from the Windows Registry. Automated registry modification is a sensitive operation that carries inherent risk.

Disclaimer: Modifying the Windows Registry can cause serious system instability if not done correctly. Quest strongly recommends backing up the registry before making any changes. Customers perform registry modifications at their own risk, and Quest is not responsible for any system damage that may occur as a result.

6. Performs a "Shrink Volume" Operation

The script initiates a volume shrink operation. This is not a fix for general disk misalignment but addresses a specific Rapid Recovery error where the partition table metadata is incorrect. Shrinking the volume by a small amount corrects this metadata.

Disruptive and May Require Reboots. Shrinking a volume can be a complex process. It may fail if "unmovable" system files (like the page file or VSS storage area) are in the way. Successfully shrinking a system volume often requires temporarily disabling these critical OS functions and rebooting the machine.

Feedback Submitted

Did this article solve an issue for you?

Select Rating

Request a KB Article

Please select your product:

To serve you better, please complete the Purpose of your Chat:

Recommended Solutions for Your Problem

Resolving Common VSS Snapshot Failures with the VSSDiagnosticScriptOnAgent.ps1 VSS Repair Script (4380518)

Title

Description

Cause

Resolution

Important Warnings

PowerShell Execution Policy Warning

Actions Performed by the Script

1. Runs chkdsk to Repair NTFS Corruption

2. Runs defrag to Mitigate Disk Fragmentation

3. Deletes Agent Change Logs (AALogs) to Free Space

4. Removes Hyper-V Checkpoints (Snapshots)

5. Detects VMware Environment to Address VSS Provider Conflicts

6. Performs a "Shrink Volume" Operation

Leave a Comment