Docs/Desktop Agent/Restore VM

Restoring Hyper-V Virtual Machines

Restore complete Hyper-V VMs from backups, including automatic VHD reassembly and re-attachment.

Overview

When you back up a Hyper-V VM, BackupEngine creates a manifest file that records the VM configuration, virtual disks, and chunk references. On restore, the agent reassembles the virtual disks from chunks and generates PowerShell commands to re-attach them to Hyper-V.

You can restore to the original host, a different Hyper-V host, or a new location on the same host.

Understanding the VM Restore Workflow

The restore process has these main steps:

•1. Select the backup: On the Restore tab, find the Hyper-V backup set and select which destination's copy to restore from.
•2. VM checklist: Verify the VM name, disks, and disk sizes. The manifest shows what will be restored.
•3. Choose target folder: Specify where to reassemble the virtual disks (e.g., C:\HyperV\VMs\vm-name\).
•4. Reassemble disks: BackupEngine downloads chunks from the backup storage (cloud or local) and reconstructs each VHD file.
•5. Generate restore commands: The agent creates RESTORE_INFO.txt with PowerShell snippets to re-attach the disks and re-start the VM.
•6. Manual re-attach: You run the PowerShell commands to create the VM in Hyper-V and start it.

Step-by-Step: Restoring a VM

•1. Click the Restore tab in the desktop agent.
•2. Find your Hyper-V backup set in the list. If multiple destinations exist, choose which copy to restore from (cloud or local).
•3. The VM checklist appears: review the VM name, number of disks, and total size. If correct, proceed.
•4. Click 'Choose Restore Location' and select or create a target folder (e.g., D:\VMs\production-web-01\).
•5. Click 'Restore' to begin downloading and reassembling disks.
•6. Restore progress shows per-disk status. Once all disks are reassembled, a RESTORE_INFO.txt file is created in the target folder.
•7. Open RESTORE_INFO.txt and review the PowerShell commands. Copy the 'New-VM' and 'Add-VMHardDiskDrive' commands.
•8. Open PowerShell as Administrator on the Hyper-V host and paste the commands to create and configure the VM.
•9. Start the VM with 'Start-VM -Name vm-name' and verify it boots correctly.

The RESTORE_INFO.txt File

After reassembly completes, a RESTORE_INFO.txt file is written to the restore folder. It contains all the information needed to re-attach the VM.

Example RESTORE_INFO.txt content

# Hyper-V VM Restore Information
# Backup Date: 2026-04-22T10:30:00Z
# VM Name: production-web-01
# Disks: 3 (C:, D:, E:)
# Total Size: 120 GB

# Step 1: Create the VM
New-VM -Name production-web-01 \
  -MemoryStartupBytes 8GB \
  -SwitchName "Default Switch"

# Step 2: Add virtual disks
Add-VMHardDiskDrive -VMName production-web-01 \
  -Path "C:\VMs\production-web-01\disk-c.vhdx" \
  -ControllerType SCSI -ControllerNumber 0

Add-VMHardDiskDrive -VMName production-web-01 \
  -Path "C:\VMs\production-web-01\disk-d.vhdx" \
  -ControllerType SCSI -ControllerNumber 0

# Step 3: Start the VM
Start-VM -Name production-web-01

Verification and Troubleshooting

•Verify chunk integrity: Each chunk is verified against its SHA-256 hash during reassembly. If a hash mismatch occurs, the backup storage is checked for bit-rot or tampering.
•Disk space: Ensure the target folder has enough space for all disks (shown in the checklist).
•Permissions: You need write access to the target folder. If using a network share, ensure it is mounted with sufficient permissions.
•Hyper-V path: The VHDX files can be stored on any volume, including a different storage pool or SAN, as long as the Hyper-V host can access the path.
•Network issues: If reassembly pauses due to network timeout, click 'Resume' to continue downloading from the last checkpoint.

⚠ Warning

Do not move or rename the VHD files after reassembly completes. The paths in RESTORE_INFO.txt are absolute and must match where the files were extracted.

Restoring to a Different Host

You can restore VM backups to a different Hyper-V host. The process is identical, except you run the PowerShell commands on the new host instead of the original.

•The restored VM gets a new UUID automatically when you create it on the new host.
•The guest OS (Windows Server, Linux, etc.) typically requires network reconfiguration or a full OS re-initialization on new hardware.
•For dissimilar hardware (e.g., different RAID controllers or NIC cards), Windows may need driver injection during startup.
•Once the guest OS boots, you may need to activate Windows or update NIC drivers.

💡 Tip

For a quick recovery to new hardware, restore to a temporary location, boot the VM with a driver USB key, let Windows Plug & Play detect new hardware, and complete the setup.

Restoring Individual Disks

If you only need one disk from the VM backup (e.g., just the C: drive), you do not have to restore all disks.

•On the VM checklist screen, toggle off the disks you do not want to restore.
•Only the selected disks will be reassembled.
•The RESTORE_INFO.txt will include Add-VMHardDiskDrive commands only for the disks you selected.

Cancelling a Running Restore (v1.11.9)

The Hyper-V restore screen shows a Cancel button while reassembly is in flight. The runner stops at the next chunk boundary (typically <1 second). Disks already finished stay on disk; the in-progress VHDX is left in place — you can delete it manually if you don't want it. Re-running the restore starts cleanly from the manifest because chunks already on local disk are not consumed by the reassembly path (chunks are server-side; only the temporary diff exports are local).

ℹ Note

See the dedicated Cancel Operations page for the cross-type matrix of what cancel does to in-flight artefacts.

Stale-VM-ID Warning (v1.11.8)

Backup sets store the Hyper-V VM's UUID. If a VM is removed and recreated (e.g. via Remove-VM + New-VM during chain-repair) the new instance gets a fresh UUID. The set still references the old one, so every subsequent backup fails with “No matching VMs found for this backup set.” v1.11.8 surfaces this as a yellow warning chip on the Hyper-V card listing the missing VM IDs alongside their saved names. The fix is to delete the set and recreate it pointing at the current VM.

Broken Disk-Chain Recovery

If the host's Hyper-V metadata references a deleted .avhdx file (the result of an interrupted differencing-disk merge — for example a host reboot in the middle of the merge, or a previous version of the agent sweeping the wrong checkpoints) every subsequent backup will fail with “VHD source file not found.” v1.11.8 detects this in a pre-flight check and refuses to take a new checkpoint on top of a broken chain — the runner surfaces a clean remediation hint (“Repair via Hyper-V Manager → VM Settings → Hard Drive” or detach + re-attach the base VHDX) instead of leaking another orphan checkpoint that compounds the problem.

ℹ Note

v1.11.8 also narrowed the orphan-checkpoint sweep to exclude BackupEngine-Reference-* snapshots — those are the long-lived incremental anchors and should never be swept on startup. The pre-1.11.8 broad pattern was the root cause of the chain-broken regression that motivated this fix.

Parallel Disks for Hyper-V Backups (v1.11.6)

For full Hyper-V backups the runner can stream multiple disks concurrently. The default concurrency is 1 (serial — same as pre-1.11.6); the runner is constructed with a maxConcurrentDisksPerVm parameter so a future setting could opt-in higher. Incremental Hyper-V backups stay serial because Export-VMSnapshot isn't safe to invoke concurrently against the same VM.

Diagnostic Logs