Skip to content

Commit 7e78cb0

Browse files
v-liannav-lianna
committed
Create hyper-v-virtual-machine-live-migration.md
1 parent 3188bcf commit 7e78cb0

1 file changed

Lines changed: 179 additions & 0 deletions

File tree

‎support/windows-server/virtualization/hyper-v-virtual-machine-live-migration.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
---
2+
title: Hyper-V Virtual Machine Live Migration Troubleshooting Guide
3+
description: Provides a comprehensive troubleshooting process, detailed solutions for common migration issues, structured data collection procedures, and quick reference resources.
4+
ms.date: 09/02/2025
5+
manager: dcscontentpm
6+
audience: itpro
7+
ms.topic: troubleshooting
8+
ms.reviewer: kaushika, jeffhugh, v-lianna
9+
ms.custom:
10+
- sap:virtualization and hyper-v\migration
11+
- pcy:WinComm Storage High Avail
12+
---
13+
# Troubleshooting Guide: Hyper-V Virtual Machine Live Migration
14+
15+
## Introduction
16+
17+
Live Migration in Hyper-V allows virtual machines (VMs) to be moved between hosts with minimal downtime—a critical feature for high availability and maintenance in Windows Server environments. Despite its capabilities, Live Migration can fail due to a wide array of factors—hardware incompatibility, authentication, network configuration, VM settings, and storage problems. Properly diagnosing and resolving Live Migration failures is vital for business continuity, especially in clustered and production settings. This guide provides a comprehensive troubleshooting process, detailed solutions for common migration issues, structured data collection procedures, and quick reference resources.
18+
19+
## Troubleshooting Checklist
20+
21+
Use this checklist as a step-wise process before and during troubleshooting:
22+
1. **Baseline Health Checks** - Confirm VM integration services are up-to-date.
23+
- Ensure all hosts are fully patched and running supported Windows Server versions.
24+
- Confirm the VM is in a supported state for migration (not in Backing Up, Stopping, etc.).
25+
2. **Cluster and Host Configuration** - Check cluster node/host compatibility (CPU, BIOS/firmware versions, configuration versions).
26+
- Verify all cluster nodes are online, healthy, and visible in Failover Cluster Manager.
27+
- Validate VM configuration version consistency across hosts.
28+
3. **Network & Storage** - Confirm live migration, management, and storage networks are correctly configured and reachable.
29+
- Ensure VM storage is accessible on the destination host.
30+
- Check firewall rules and port accessibility (e.g., UDP 3343 for WSFC).
31+
4. **Authentication/Permissions** - Verify Kerberos or CredSSP is enabled and delegated properly for live migrations.
32+
- Check required Service Principal Names (SPNs) are registered.
33+
- Confirm permission levels for migration accounts.
34+
5. **Virtual Switches/Networks** - Ensure required VM switches exist and are identically configured across hosts.
35+
- Validate network teaming (SET or LBFO) consistency.
36+
6. **VM-Specific Features** - If using vTPM/Shielded VM, confirm certificate requirements between hosts.
37+
- Check for snapshots/checkpoints—merge or delete as appropriate.
38+
39+
## Common Issues and Their Respective Solutions
40+
41+
### 1. **Hardware/CPU Incompatibility**
42+
43+
**Symptoms:**
44+
- Error: “The virtual machine uses processor-specific features not supported on the physical computer”
45+
- Event ID 21502
46+
47+
**Resolution:**
48+
- In Hyper-V Manager, set VM’s processor settings: Enable “Migrate to a physical computer with a different processor version”.
49+
- Ensure target host supports VM’s CPU features.
50+
- *Tip:* Always start VMs for the first time on the oldest (least capable) CPU host.
51+
52+
### 2. **VM Configuration Version Mismatch**
53+
54+
**Symptoms:**
55+
- Migration works one way but not in reverse (esp. after moving to a newer OS).
56+
- Error: Live migration or quick migration fails with compatibility issues.
57+
- Event IDs 10698, 21502
58+
59+
**Resolution:**
60+
- Upgrade VM configuration version when moving to a newer host (Hyper-V Manager: Action > Upgrade VM Configuration Version).
61+
- *Note:* Cannot roll back; VMs with upgraded version cannot be migrated back to older hosts.
62+
- Verify configuration versions with Get-VM \* | select Name, Version.
63+
64+
### 3. **Network Connectivity/Configuration Issues**
65+
66+
**Symptoms:**
67+
- Live migration fails before/during transfer.
68+
- Migration fails with: "The client cannot connect to the destination specified in the request" or "WinRM protocol errors."
69+
- Event IDs: 20406, 280
70+
71+
**Resolution:**
72+
- Ensure hosts can resolve and reach each other via hostname/IP (test with ping).
73+
- Use winrm quickconfig to verify/configure WinRM on both hosts.
74+
- Update TrustedHosts as needed:Set-Item WSMan:\localhost\Client\TrustedHosts -Value "<Host1>,<Host2>"
75+
- Verify firewall allows necessary ports (default SMB, WinRM, and clustering ports).
76+
- Match network configurations (switch names/types, teaming) across hosts.
77+
78+
### 4. **Authentication/Delegation Problems**
79+
80+
**Symptoms:**
81+
- Error code: “General access denied error (0x80070005)”
82+
- Errors 0x8009030E, 0x8009030D (delegation/Kerberos/SPN problems)
83+
84+
**Resolution:**
85+
- Enable Kerberos authentication:Hyper-V Settings > Live Migrations > Advanced > Authentication protocol: Kerberos
86+
- Configure constrained delegation in AD: - Computer Properties > Delegation tab > Trust this computer for delegation to specified services only > Add cifs and Microsoft Virtual System Migration Service.
87+
- Register missing SPNs: setspn -s Microsoft Virtual System Migration Service/<FQDN> <ComputerName>
88+
- Purge old Kerberos tickets:KLIST PURGE -li 0x3e7
89+
90+
### 5. **Storage/Shared Disk Issues**
91+
92+
**Symptoms:**
93+
- Migration fails for VMs with shared VHDX/shared disks
94+
- Error: Shared disk missing in migration options.
95+
96+
**Resolution:**
97+
- Shared virtual disks can only be used in clustered VM roles and cannot be migrated using standard methods.
98+
- Manually move and reattach shared disks at destination where required.
99+
100+
### 6. **vTPM/Shielded VM Certificate Issues**
101+
102+
**Symptoms:**
103+
- Error: "The key protector for the virtual machine could not be unwrapped."
104+
- Migration only fails for vTPM-protected VMs.
105+
106+
**Resolution:**
107+
- Export Shielding/Key Protector certificates from source host and import on destination.
108+
- Windows Certificates Snap-in (certmgr.msc) can be used.
109+
- PowerShell: Export-PfxCertificate and Import-PfxCertificate
110+
111+
### 7. **State File/Checkpoint Problems**
112+
113+
**Symptoms:**
114+
- Error: “Cannot restore this virtual machine because the saved state data cannot be read. Delete the saved state data and then try to start the virtual machine. (0xC0370027)”
115+
- VMs stuck in “Backing up” state
116+
117+
**Resolution:**
118+
- In Hyper-V Manager: Select VM > Delete Saved State
119+
- Manually delete .bin and .vsv files from VM folder if necessary.
120+
- Remove or merge corrupted checkpoints.
121+
122+
### 8. **Cluster/Migration Limit Issues**
123+
124+
**Symptoms:**
125+
- Error: “Virtual machine migration limit 1 was reached, please wait for completion of an ongoing migration operation.”
126+
- VMs enter Saved state during node drain or reboot.
127+
128+
**Resolution:**
129+
- Increase Simultaneous Migrations:Hyper-V Settings > Live Migrations > Simultaneous Migrations
130+
- PowerShell:Set-VMHost -MaximumVirtualMachineMigrations N
131+
- Always drain roles before reboot with:Suspend-ClusterNode -Name <NodeName> -Drain
132+
133+
### 9. **Code Defects/Bugs**
134+
135+
**Symptoms:**
136+
- VMs stuck in “Stopping” state after migration; orphaned vport reported in livedump analysis.
137+
- Case #: 2502260050001354003
138+
139+
**Resolution:**
140+
- Update to latest Windows Server Cumulative Update.
141+
- If upgrade not possible, request Microsoft support for hotfix if bug is referenced.
142+
143+
## Data Collection
144+
145+
**Standard Data Collection Checklist:**
146+
- **Event Logs:**Get-WinEvent -LogName "Microsoft-Windows-Hyper-V-VMMS/Admin"
147+
- **Cluster Logs:**Get-ClusterLog -UseLocalTime -Destination <Path>
148+
- **Hyper-V Migration Logs:**Get-WinEvent -LogName Microsoft-Windows-Hyper-V-Worker-Admin
149+
- **Network Diagnostics:**Get-NetAdapter, ipconfig /all, and ensure all network paths are up.
150+
- **Delegation and SPN Checks:**setspn -L <HostName>, check Delegation tab in AD.
151+
- **VM and System Configuration:**Get-VM \* | select Name, Version Get-VMSwitch Get-VMProcessor -VMName <VMName>
152+
- **WinRM Configuration:**winrm quickconfig Set-Item WSMan:\localhost\Client\TrustedHosts -Value "<Host1>,<Host2>"
153+
- **PowerShell to Gather Live Migration Traces:**TSS.ps1 -CollectLog SHA_support-all -noBasicLog -noUpdate -NewSession
154+
- **Snapshot/Checkpoint Chain:**Get-VHDChain -Path <PathToVHD>
155+
156+
## Common Issues Quick Reference Table
157+
158+
| Symptom/Error | Likely Root Cause | Resolution Summary |
159+
| --- | --- | --- |
160+
| "The VM uses processor-specific features not supported..." | CPU feature/BIOS/firmware mismatch | Enable migration compatibility; check host CPU features and BIOS |
161+
| VM migration fails with version error | Config version mismatch | Upgrade VM config version on new host, can't migrate back to old host |
162+
| "General access denied error (0x80070005)", 0x8009030E/0x8009030D | SPN/delegation/Kerberos misconfig | Configure constrained delegation, register SPNs, set Kerberos, check AD |
163+
| "The server does not support WS-Management Identify operations..." | WinRM/proxy/trustedhosts misconfig | Set WinRM/trusted hosts, update hosts files, bypass proxy |
164+
| "Cannot restore this virtual machine because the saved state data..." | Corrupt checkpoint/saved state files | Delete Saved State, remove/merge checkpoints, manually delete .bin/.vsv |
165+
| vTPM-enabled VM fails: "The key protector... could not be unwrapped." | Certificate/Shielded VM config | Export/import key protector certificates |
166+
| Migration fails—shared disk not available in migration wizard | Unsupported scenario | Manual re-attach disks, follow shared disk migration documentation |
167+
| Live migration limit reached; VMs enter Saved state in draining | Concurrency settings low; improper drain | Raise migration limit, drain roles before reboot |
168+
| "No matching virtual switch found..." | Network switch config inconsistency | Ensure identical virtual switch config on all hosts |
169+
| Live migration events show failures post-update | Patch/Firmware/Speculation setting | Ensure all nodes are updated/patched; check speculation control settings |
170+
| VM backs up forever, can't move/out/in "Backing up" state | Backup software lock | Restart backup service, VMMS service, or power on VM to merge checkpoints |
171+
172+
## References
173+
- **WinRM and TrustedHosts Configuration:**[<u>https://learn.microsoft.com/en-us/windows/win32/winrm/installation-and-configuration-for-windows-remote-management</u>](https://learn.microsoft.com/en-us/windows/win32/winrm/installation-and-configuration-for-windows-remote-management)
174+
- **Cluster Shared Volumes and Migration Limits:**[<u>https://learn.microsoft.com/en-us/windows-server/failover-clustering/failover-cluster-csvs</u>](https://learn.microsoft.com/en-us/windows-server/failover-clustering/failover-cluster-csvs)
175+
- **SCVMM VMware-to-Hyper-V Conversion:**[<u>https://learn.microsoft.com/en-us/system-center/vmm/vm-convert-vmware?view=sc-vmm-2022</u>](https://learn.microsoft.com/en-us/system-center/vmm/vm-convert-vmware?view=sc-vmm-2022)
176+
177+
## Summary
178+
179+
Ensuring successful Hyper-V Live Migration requires diligent configuration management—including CPU, firmware, network, authentication, storage, and permissions—across all participating hosts. By following the troubleshooting checklist, addressing known root causes as outlined in the solutions section, and using targeted data collection, most migration failures can be swiftly resolved or appropriately escalated. Staying current with patches, standardizing cluster configurations, and understanding log outputs will minimize downtime and operational risk for mission-critical virtual machine workloads.

0 commit comments

Comments
 (0)