Skip to content

Commit 30cd9b2

Browse files
v-liannav-lianna
committed
updates
1 parent 7e78cb0 commit 30cd9b2

2 files changed

Lines changed: 148 additions & 88 deletions

File tree

‎support/windows-server/toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2798,6 +2798,8 @@ items:
27982798
items:
27992799
- name: 'Troubleshooting guidance: Live Migration'
28002800
href: ./virtualization/troubleshoot-live-migration-guidance.md
2801+
- name: 'Troubleshooting guide: Hyper-V virtual machine live migration'
2802+
href: ./virtualization/hyper-v-virtual-machine-live-migration.md
28012803
- name: Can't migrate a virtual machine from one host to another
28022804
href: ./virtualization/unable-migrate-virtual-machine-processor-not-compatible-host.md
28032805
- name: Starting or live migrating Hyper-V VMs fails

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

Lines changed: 146 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -10,156 +10,213 @@ ms.custom:
1010
- sap:virtualization and hyper-v\migration
1111
- pcy:WinComm Storage High Avail
1212
---
13-
# Troubleshooting Guide: Hyper-V Virtual Machine Live Migration
13+
# Troubleshooting guide: Hyper-V virtual machine live migration
1414

15-
## Introduction
15+
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.
1616

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
17+
## Troubleshooting checklist
2018

2119
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.
20+
21+
1. Baseline health checks
22+
23+
- Confirm VM integration services are up-to-date.
2324
- 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).
25+
- Confirm the VM is in a supported state for migration (for example, not in backing up or stopping).
26+
27+
1. Cluster and host configuration
28+
29+
- Check cluster node/host compatibility (CPU, BIOS/firmware versions, configuration versions).
2630
- Verify all cluster nodes are online, healthy, and visible in Failover Cluster Manager.
2731
- Validate VM configuration version consistency across hosts.
28-
3. **Network & Storage** - Confirm live migration, management, and storage networks are correctly configured and reachable.
32+
33+
1. Network and storage
34+
35+
- Confirm live migration, management, and storage networks are correctly configured and reachable.
2936
- 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.
37+
- Check firewall rules and port accessibility (for example, UDP 3343 for WSFC).
38+
39+
1. Authentication or permissions
40+
41+
- Verify Kerberos or CredSSP is enabled and delegated properly for live migrations.
3242
- Check required Service Principal Names (SPNs) are registered.
3343
- Confirm permission levels for migration accounts.
34-
5. **Virtual Switches/Networks** - Ensure required VM switches exist and are identically configured across hosts.
44+
45+
1. Virtual switches or networks
46+
47+
- Ensure required VM switches exist and are identically configured across hosts.
3548
- Validate network teaming (SET or LBFO) consistency.
36-
6. **VM-Specific Features** - If using vTPM/Shielded VM, confirm certificate requirements between hosts.
49+
50+
1. VM-specific features
51+
52+
- If using vTPM/Shielded VM, confirm certificate requirements between hosts.
3753
- Check for snapshots/checkpoints—merge or delete as appropriate.
3854

39-
## Common Issues and Their Respective Solutions
55+
Here are common issues and their respective resolutions:
56+
57+
## Hardware or CPU incompatibility
58+
59+
Symptoms:
4060

41-
### 1. **Hardware/CPU Incompatibility**
61+
- Error message:
4262

43-
**Symptoms:**
44-
- Error: “The virtual machine uses processor-specific features not supported on the physical computer”
63+
> The virtual machine uses processor-specific features not supported on the physical computer
4564
- Event ID 21502
4665

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.
66+
### Resolution
5167

52-
### 2. **VM Configuration Version Mismatch**
68+
- In Hyper-V Manager, set VM's processor settings: Enable **Migrate to a physical computer with a different processor version**.
69+
- Ensure target host supports VM's CPU features.
5370

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.
71+
> [!TIP]
72+
> Always start VMs for the first time on the oldest (least capable) CPU host.
73+
74+
## VM configuration version mismatch
75+
76+
Symptoms:
77+
78+
- Migration works one way but not in reverse (especially after moving to a newer OS).
79+
- Error message:
80+
81+
> Live migration or quick migration fails with compatibility issues.
5782
- Event IDs 10698, 21502
5883

59-
**Resolution:**
84+
### Resolution
85+
6086
- 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.
6387

64-
### 3. **Network Connectivity/Configuration Issues**
88+
> [!NOTE]
89+
> Can't roll back; VMs with upgraded version can't be migrated back to older hosts.
90+
91+
- Verify configuration versions with the `Get-VM * | select Name, Version` cmdlet.
92+
93+
## Network connectivity or configuration issues
94+
95+
Symptoms:
6596

66-
**Symptoms:**
6797
- Live migration fails before/during transfer.
6898
- Migration fails with: "The client cannot connect to the destination specified in the request" or "WinRM protocol errors."
6999
- Event IDs: 20406, 280
70100

71-
**Resolution:**
72-
- Ensure hosts can resolve and reach each other via hostname/IP (test with ping).
101+
### Resolution
102+
103+
- Ensure hosts can resolve and reach each other via hostname/IP (test with `ping`).
73104
- Use winrm quickconfig to verify/configure WinRM on both hosts.
74-
- Update TrustedHosts as needed:Set-Item WSMan:\localhost\Client\TrustedHosts -Value "<Host1>,<Host2>"
105+
- Update TrustedHosts as needed: `Set-Item WSMan:\localhost\Client\TrustedHosts -Value "<Host1>,<Host2>"`
75106
- Verify firewall allows necessary ports (default SMB, WinRM, and clustering ports).
76107
- Match network configurations (switch names/types, teaming) across hosts.
77108

78-
### 4. **Authentication/Delegation Problems**
109+
## Authentication or delegation problems
110+
111+
Symptoms:
79112

80-
**Symptoms:**
81-
- Error code: “General access denied error (0x80070005)”
113+
- Error code: "General access denied error (0x80070005)"
82114
- Errors 0x8009030E, 0x8009030D (delegation/Kerberos/SPN problems)
83115

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
116+
### Resolution
89117

90-
### 5. **Storage/Shared Disk Issues**
118+
- Enable Kerberos authentication: **Hyper-V Settings** > **Live Migrations** > **Advanced** > **Authentication protocol: Kerberos**.
119+
- 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**.
120+
- Register missing SPNs: `setspn -s Microsoft Virtual System Migration Service/<FQDN> <ComputerName>`
121+
- Purge old Kerberos tickets: `KLIST PURGE -li 0x3e7`
122+
123+
## Storage or shared disk issues
124+
125+
Symptoms:
91126

92-
**Symptoms:**
93127
- Migration fails for VMs with shared VHDX/shared disks
94128
- Error: Shared disk missing in migration options.
95129

96-
**Resolution:**
97-
- Shared virtual disks can only be used in clustered VM roles and cannot be migrated using standard methods.
130+
### Resolution
131+
132+
- Shared virtual disks can only be used in clustered VM roles and can't be migrated using standard methods.
98133
- Manually move and reattach shared disks at destination where required.
99134

100-
### 6. **vTPM/Shielded VM Certificate Issues**
135+
## VTPM or shielded VM certificate issues
136+
137+
Symptoms:
101138

102-
**Symptoms:**
103139
- Error: "The key protector for the virtual machine could not be unwrapped."
104140
- Migration only fails for vTPM-protected VMs.
105141

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
142+
### Resolution
143+
144+
- Export shielding or key protector certificates from source host and import on destination.
145+
- Windows certificates snap-in (**certmgr.msc**) can be used.
146+
- PowerShell cmdlet:
147+
148+
```powershell
149+
Export-PfxCertificate and Import-PfxCertificate
150+
```
110151

111-
### 7. **State File/Checkpoint Problems**
152+
## State file or checkpoint problems
112153

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
154+
Symptoms:
116155

117-
**Resolution:**
118-
- In Hyper-V Manager: Select VM > Delete Saved State
119-
- Manually delete .bin and .vsv files from VM folder if necessary.
156+
- Error message:
157+
158+
> 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)
159+
- VMs stuck in "Backing up" state
160+
161+
### Resolution
162+
163+
- In Hyper-V Manager: Select **VM** > **Delete Saved State**.
164+
- Manually delete `.bin` and `.vsv` files from VM folder if necessary.
120165
- Remove or merge corrupted checkpoints.
121166

122-
### 8. **Cluster/Migration Limit Issues**
167+
## Cluster or migration limit issues
168+
169+
Symptoms:
123170

124-
**Symptoms:**
125-
- Error: “Virtual machine migration limit 1 was reached, please wait for completion of an ongoing migration operation.”
171+
- Error message:
172+
173+
> Virtual machine migration limit 1 was reached, please wait for completion of an ongoing migration operation.
126174
- VMs enter Saved state during node drain or reboot.
127175

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
176+
### Resolution
177+
178+
- Increase Simultaneous Migrations: **Hyper-V Settings** > **Live Migrations** > **Simultaneous Migrations**.
179+
- PowerShell cmdlet:
180+
181+
```powershell
182+
Set-VMHost -MaximumVirtualMachineMigrations N
183+
```
132184

133-
### 9. **Code Defects/Bugs**
185+
- Always drain roles before reboot with: `Suspend-ClusterNode -Name <NodeName> -Drain`
134186

135-
**Symptoms:**
136-
- VMs stuck in “Stopping” state after migration; orphaned vport reported in livedump analysis.
137-
- Case #: 2502260050001354003
187+
## Code defects or bugs
188+
189+
Symptoms:
190+
191+
- VMs stuck in "Stopping" state after migration; orphaned vport reported in live dump analysis.
192+
- Case number: 2502260050001354003
193+
194+
### Resolution
138195

139-
**Resolution:**
140196
- Update to latest Windows Server Cumulative Update.
141197
- If upgrade not possible, request Microsoft support for hotfix if bug is referenced.
142198

143-
## Data Collection
199+
## Data collection
144200

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>
201+
Standard data collection checklist:
155202

156-
## Common Issues Quick Reference Table
203+
- Event logs: `Get-WinEvent -LogName "Microsoft-Windows-Hyper-V-VMMS/Admin"`
204+
- Cluster logs: `Get-ClusterLog -UseLocalTime -Destination <Path>`
205+
- Hyper-V migration logs: `Get-WinEvent -LogName Microsoft-Windows-Hyper-V-Worker-Admin`
206+
- Network diagnostics: `Get-NetAdapter`, `ipconfig /all`, and ensure all network paths are up.
207+
- Delegation and SPN checks: run `setspn -L <HostName>`, and check **Delegation** tab in AD.
208+
- VM and system configuration: `Get-VM * | select Name, Version`, `Get-VMSwitch`, and `Get-VMProcessor -VMName <VMName>`.
209+
- WinRM configuration: `winrm quickconfig Set-Item WSMan:\localhost\Client\TrustedHosts -Value "<Host1>,<Host2>"`
210+
- PowerShell to gather live migration traces: `TSS.ps1 -CollectLog SHA_support-all -noBasicLog -noUpdate -NewSession`
211+
- Snapshot or checkpoint chain: `Get-VHDChain -Path <PathToVHD>`
157212

158-
| Symptom/Error | Likely Root Cause | Resolution Summary |
213+
## Common issues quick reference table
214+
215+
| Symptom or error | Likely root cause | Resolution summary |
159216
| --- | --- | --- |
160217
| "The VM uses processor-specific features not supported..." | CPU feature/BIOS/firmware mismatch | Enable migration compatibility; check host CPU features and BIOS |
161218
| 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 |
219+
| "General access denied error (0x80070005)," 0x8009030E/0x8009030D | SPN/delegation/Kerberos misconfig | Configure constrained delegation, register SPNs, set Kerberos, check AD |
163220
| "The server does not support WS-Management Identify operations..." | WinRM/proxy/trustedhosts misconfig | Set WinRM/trusted hosts, update hosts files, bypass proxy |
164221
| "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 |
165222
| vTPM-enabled VM fails: "The key protector... could not be unwrapped." | Certificate/Shielded VM config | Export/import key protector certificates |
@@ -170,10 +227,11 @@ Use this checklist as a step-wise process before and during troubleshooting:
170227
| 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 |
171228

172229
## 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)
230+
231+
- WinRM and `TrustedHosts` configuration: [Installation and configuration for Windows Remote Management](/windows/win32/winrm/installation-and-configuration-for-windows-remote-management)
232+
- Cluster Shared Volumes and migration limits: [Cluster Shared Volumes overview](/windows-server/failover-clustering/failover-cluster-csvs)
233+
- SCVMM VMware-to-Hyper-V conversion: [Convert a VMware VM to Hyper-V in the VMM fabric](/system-center/vmm/vm-convert-vmware)
176234

177235
## Summary
178236

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.
237+
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 minimize downtime and operational risk for mission-critical virtual machine workloads.

0 commit comments

Comments
 (0)