Skip to content

Commit f42f439

Browse files
committed
troubleshooting: mention specific HCS_E_HYPERV_NOT_INSTALLED error code
Inspired by docker/for-win#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 <dave.scott@docker.com>
1 parent 73669a1 commit f42f439

File tree

1 file changed

+24
-1
lines changed
  • content/manuals/desktop/troubleshoot-and-support/troubleshoot

1 file changed

+24
-1
lines changed

content/manuals/desktop/troubleshoot-and-support/troubleshoot/topics.md

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -343,13 +343,21 @@ Also, the `\` character has a special meaning in Git Bash.
343343

344344
Portability of the scripts is not affected as Linux treats multiple `/` as a single entry.
345345

346-
### Docker Desktop fails due to Virtualization settings
346+
### Docker Desktop fails due to Virtualization not working
347+
348+
#### Error message
349+
350+
A typical error message is "Docker Deskop - Unexpected WSL error" mentioning the error code
351+
`Wsl/Service/RegisterDistro/CreateVm/HCS/HCS_E_HYPERV_NOT_INSTALLED`. Manually executing `wsl` commands
352+
will also fail with the same error code.
347353

348354
#### Cause
349355

350356
- Virtualization settings are disabled in the BIOS.
351357
- Windows Hyper-V or WSL 2 components are missing.
352358

359+
Note some third-party software such as Android emulators will disable Hyper-V on install.
360+
353361
#### Solutions
354362

355363
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
364372

365373
![WSL 2 enabled](../../images/wsl2-enabled.png)
366374

375+
It must be possible to run WSL 2 commands without error, for example
376+
377+
```console
378+
PS C:\users\> wsl -l -v
379+
NAME STATE VERSION
380+
* Ubuntu Running 2
381+
docker-desktop Stopped 2
382+
PS C:\users\> wsl -d docker-desktop echo WSL 2 is working
383+
WSL 2 is working
384+
```
385+
386+
If the features are enabled but the commands are not working, first check [Virtualization is turned on](#virtualization-must-be-turned-on)
387+
then [enable the Hypervisor at Windows startup](#hypervisor-enabled-at-windows-startup) if required. If running Docker
388+
Desktop in a Virtual Machine, ensure [the hypervisor has nested virtualization enabled](#turn-on-nested-virtualization).
389+
367390
##### Hyper-V
368391

369392
On Windows 10 Pro or Enterprise, you can also use Hyper-V with the following features enabled:

0 commit comments

Comments
 (0)