From b92705bdd35127553e53c844272507a9c311dabd Mon Sep 17 00:00:00 2001 From: David Scott Date: Thu, 15 May 2025 10:58:20 +0100 Subject: [PATCH 1/2] troubleshooting: mention specific HCS_E_HYPERV_NOT_INSTALLED error code Inspired by https://github.com/docker/for-win/issues/14743 The troubleshooting contains the relevant info, but this PR - explicitly mentions a common error code (hopefully helping people find this advice) - emphasises that, in WSL 2 mode, WSL 2 commands must be working before Docker Desktop can start - highlight a common scenario where an android emulator is installed which disables Hyper-V (because it uses a conflicting hypervisor) The structure is currently - WSL 2 only - Hyper-V only - Common to both So add links to the WSL 2 section to the common section to make sure people realise it's relevant. Signed-off-by: David Scott --- .../troubleshoot/topics.md | 25 ++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/content/manuals/desktop/troubleshoot-and-support/troubleshoot/topics.md b/content/manuals/desktop/troubleshoot-and-support/troubleshoot/topics.md index ba3ff6953ae..cd6ac7d3583 100644 --- a/content/manuals/desktop/troubleshoot-and-support/troubleshoot/topics.md +++ b/content/manuals/desktop/troubleshoot-and-support/troubleshoot/topics.md @@ -343,13 +343,21 @@ Also, the `\` character has a special meaning in Git Bash. Portability of the scripts is not affected as Linux treats multiple `/` as a single entry. -### Docker Desktop fails due to Virtualization settings +### Docker Desktop fails due to Virtualization not working + +#### Error message + +A typical error message is "Docker Desktop - Unexpected WSL error" mentioning the error code +`Wsl/Service/RegisterDistro/CreateVm/HCS/HCS_E_HYPERV_NOT_INSTALLED`. Manually executing `wsl` commands +will also fail with the same error code. #### Cause - Virtualization settings are disabled in the BIOS. - Windows Hyper-V or WSL 2 components are missing. +Note some third-party software such as Android emulators will disable Hyper-V on install. + #### Solutions Your machine must have the following features for Docker Desktop to function correctly: @@ -364,6 +372,21 @@ Your machine must have the following features for Docker Desktop to function cor ![WSL 2 enabled](../../images/wsl2-enabled.png) +It must be possible to run WSL 2 commands without error, for example + +```console +PS C:\users\> wsl -l -v + NAME STATE VERSION +* Ubuntu Running 2 + docker-desktop Stopped 2 +PS C:\users\> wsl -d docker-desktop echo WSL 2 is working +WSL 2 is working +``` + +If the features are enabled but the commands are not working, first check [Virtualization is turned on](#virtualization-must-be-turned-on) +then [enable the Hypervisor at Windows startup](#hypervisor-enabled-at-windows-startup) if required. If running Docker +Desktop in a Virtual Machine, ensure [the hypervisor has nested virtualization enabled](#turn-on-nested-virtualization). + ##### Hyper-V On Windows 10 Pro or Enterprise, you can also use Hyper-V with the following features enabled: From 424e8bd5d9cf3eb1e621b31d564aaae763e248f8 Mon Sep 17 00:00:00 2001 From: Allie Sadler <102604716+aevesdocker@users.noreply.github.com> Date: Thu, 15 May 2025 13:16:03 +0100 Subject: [PATCH 2/2] Apply suggestions from code review --- .../desktop/troubleshoot-and-support/troubleshoot/topics.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/manuals/desktop/troubleshoot-and-support/troubleshoot/topics.md b/content/manuals/desktop/troubleshoot-and-support/troubleshoot/topics.md index cd6ac7d3583..a234191093c 100644 --- a/content/manuals/desktop/troubleshoot-and-support/troubleshoot/topics.md +++ b/content/manuals/desktop/troubleshoot-and-support/troubleshoot/topics.md @@ -349,7 +349,7 @@ Portability of the scripts is not affected as Linux treats multiple `/` as a sin A typical error message is "Docker Desktop - Unexpected WSL error" mentioning the error code `Wsl/Service/RegisterDistro/CreateVm/HCS/HCS_E_HYPERV_NOT_INSTALLED`. Manually executing `wsl` commands -will also fail with the same error code. +also fails with the same error code. #### Cause @@ -372,7 +372,7 @@ Your machine must have the following features for Docker Desktop to function cor ![WSL 2 enabled](../../images/wsl2-enabled.png) -It must be possible to run WSL 2 commands without error, for example +It must be possible to run WSL 2 commands without error, for example: ```console PS C:\users\> wsl -l -v