Map HCS_E_HYPERV_NOT_INSTALLED to an actionable 'install Virtual Machine Platform' error#40723
Open
benhillis wants to merge 1 commit into
Open
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR improves the WSL service’s WSL1→WSL2 conversion path by adding an early pre-flight check for the Virtual Machine Platform optional component, so the conversion fails with a WSL-defined error and actionable guidance instead of surfacing a low-level HCS failure mid-conversion.
Changes:
- Add a pre-flight
IsVirtualMachinePlatformInstalled()check inLxssUserSessionImpl::SetVersion(WSL1→WSL2 branch). - Throw
WSL_E_VIRTUAL_MACHINE_PLATFORM_REQUIREDwith a user-facing error message when the optional component is missing.
Comment on lines
+2028
to
+2031
| THROW_HR_WITH_USER_ERROR_IF( | ||
| WSL_E_VIRTUAL_MACHINE_PLATFORM_REQUIRED, | ||
| wsl::shared::Localization::MessageVirtualMachinePlatformNotInstalled(), | ||
| !wsl::windows::common::wslutil::IsVirtualMachinePlatformInstalled()); |
benhillis
commented
Jun 5, 2026
| // installed before creating the utility VM; otherwise VM creation fails deep in HCS with a raw | ||
| // HCS_E_HYPERV_NOT_INSTALLED, which surfaces as a confusing error mid-conversion. Failing here is | ||
| // safe because no distribution artifacts have been modified yet (deleteFlags is still 0). | ||
| THROW_HR_WITH_USER_ERROR_IF( |
Member
Author
There was a problem hiding this comment.
Hmm maybe this should just be in _CreateVm?
benhillis
force-pushed
the
user/benhillis/setversion-vmp-preflight
branch
from
4ff0457 to
a9a0f67
Compare
…achine Platform Any operation that needs the WSL2 utility VM (launch, 'wsl --set-version <distro> 2' conversion, 'wsl --import', disk mount, ...) funnels through LxssUserSessionImpl::_CreateVm() -> WslCoreVm::Create() -> hcs::CreateComputeSystem(). On a machine without the Virtual Machine Platform optional component, HCS throws HCS_E_HYPERV_NOT_INSTALLED there. That HRESULT is mapped (wslutil.cpp) to MessageEnableVirtualization() - 'WSL2 is unable to start since virtualization is not enabled on this machine' - which points the user at their BIOS instead of the actual cause: the missing optional component. This is especially confusing during a WSL1->WSL2 conversion (internal Sev1 customer report). Catch HCS_E_HYPERV_NOT_INSTALLED at the WslCoreVm::Create() call site in _CreateVm() and remap it to the existing (previously unused) WSL_E_VIRTUAL_MACHINE_PLATFORM_REQUIRED, which is already mapped to an actionable 'install Virtual Machine Platform via wsl.exe --install --no-distribution' message. Handling it at this single chokepoint fixes every VM-creation path uniformly and gives callers/telemetry a meaningful WSL error code instead of a raw HCS code. Keying off the actual creation failure (rather than a pre-flight service-presence check) deliberately leaves other cases untouched: when the Virtual Machine Platform is only partially present (e.g. vmcompute up but HNS/vfpext missing) CreateComputeSystem() still succeeds and the VM starts, and WslCoreVm's existing networking fallback continues to warn and degrade to no-networking as before. All other Create() failures are rethrown unchanged. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
benhillis
force-pushed
the
user/benhillis/setversion-vmp-preflight
branch
from
a9a0f67 to
0a3cb4f
Compare
benhillis
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
Any op that needs the WSL2 VM (launch,
--set-version 2,--import, disk mount) goes through_CreateVm()->WslCoreVm::Create()->hcs::CreateComputeSystem(). Without the Virtual Machine Platform optional component, HCS throwsHCS_E_HYPERV_NOT_INSTALLED, which maps to "virtualization is not enabled on this machine" — pointing users at their BIOS instead of the real cause (missing optional component). Especially confusing mid--set-versionconversion (internal Sev1).Fix
Catch
HCS_E_HYPERV_NOT_INSTALLEDat theCreate()call in_CreateVm()and remap toWSL_E_VIRTUAL_MACHINE_PLATFORM_REQUIRED(already defined + mapped to "install Virtual Machine Platform via wsl.exe --install --no-distribution", just never thrown). One chokepoint fixes every VM-creation path. Keying off the actual failure means the partial-VMP case (vmcomputeup,HNS/vfpextmissing) still starts with degraded networking as before — no collateral.Notes
MessageVirtualMachinePlatformNotInstalled; its "Failed to start virtual networking" prefix is slightly off here — can add a dedicated string if preferred.