How to fix Docker Desktop - Unexpected WSL error in Docker

DockerINTERMEDIATEMEDIUMUpdated Dec 1, 2025· 644 views

This error occurs when Docker Desktop fails to communicate with the Windows Subsystem for Linux (WSL 2) backend. It typically appears on Windows 10/11 when WSL components are misconfigured, outdated, or conflicting with other software like VPNs or Hyper-V settings.

Quick fix

Fixes Docker Desktop - Unexpected WSL error

wsl --shutdown
  1. Restart WSL and Docker Desktop
  2. Update WSL to the latest version
  3. Enable required Windows features
  4. Ensure the Hyper-V hypervisor is enabled
docker — error
wsl --shutdown
Docker Desktop - Unexpected WSL error

What this error means

Docker Desktop on Windows uses WSL 2 (Windows Subsystem for Linux) as its default backend for running Linux containers. When Docker starts, it creates two WSL distributions: 'docker-desktop' and 'docker-desktop-data'. The 'Unexpected WSL error' message indicates that Docker cannot properly initialize or communicate with these WSL distributions. This can happen for several reasons: the required Windows features (Virtual Machine Platform, WSL) might not be enabled, the Hyper-V hypervisor might be disabled, the WSL kernel might be outdated, or there could be conflicts with VPN software or other virtualization tools. In some cases, the Docker WSL distributions themselves become corrupted and need to be re-registered.

Typical symptoms

  • Docker Desktop shows 'Unexpected WSL error' dialog on startup
  • Error message mentions 'An unexpected error was encountered while executing a WSL command'
  • Docker Desktop fails to start or gets stuck at 'Starting...'
  • WSL distributions 'docker-desktop' or 'docker-desktop-data' are missing when running 'wsl -l -v'
  • Error codes like 0x80070422, 0x8037011e, or 4294967295 appear
  • Docker worked before a Windows update or system restart

Common causes

  1. Virtual Machine Platform Windows feature is not enabled
  2. Hyper-V hypervisor is disabled in boot configuration
  3. WSL 2 kernel is outdated and needs updating
  4. VPN software (like NordVPN) is interfering with WSL networking
  5. Docker Desktop WSL distributions are corrupted or missing
  6. Virtualization is disabled in BIOS/UEFI settings
  7. Recent Windows update broke WSL compatibility
  8. Docker was installed to a custom location causing path issues
  9. Host Compute Service is stopped or malfunctioning

How to fix "Docker Desktop - Unexpected WSL error"

1Restart WSL and Docker Desktop

Start with the simplest fix. Open PowerShell or Command Prompt as Administrator and run:

powershell
wsl --shutdown

Wait a few seconds, then restart Docker Desktop. This terminates all WSL instances and often resolves temporary issues.

2Update WSL to the latest version

An outdated WSL kernel is a common cause. Run these commands as Administrator:

powershell
wsl --update

If that fails, download the manual installer from https://aka.ms/wsl2kernel and run the wsl_update_x64.msi file.

3Enable required Windows features

Docker Desktop requires Virtual Machine Platform and WSL. Open PowerShell as Administrator:

powershell
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Restart your computer after enabling these features.

4Ensure the Hyper-V hypervisor is enabled

Check if the hypervisor is enabled:

powershell
bcdedit /enum | findstr -i hypervisorlaunchtype

If you see hypervisorlaunchtype Off, enable it with:

powershell
bcdedit /set hypervisorlaunchtype Auto

Restart your computer for changes to take effect.

5Check for VPN interference

VPN software, especially NordVPN, can interfere with WSL networking. Try:

1. Disconnect from VPN (keep the app running, just disconnect)
2. Restart Docker Desktop
3. If Docker works, you may need to configure split tunneling or disable VPN while using Docker

6Reset Winsock if networking is broken

Network configuration issues can prevent WSL from working. Run as Administrator:

powershell
netsh winsock reset

Restart your computer after running this command.

7Unregister and let Docker recreate WSL distributions

If the Docker WSL distributions are corrupted, remove them so Docker can recreate them:

powershell
wsl --unregister docker-desktop
wsl --unregister docker-desktop-data

Warning: This will delete all Docker containers and images. Back up important data first using docker save and docker export.

After unregistering, restart Docker Desktop. It will recreate the distributions automatically.

8Delete Docker Desktop settings file

A corrupted settings file can prevent Docker from starting. Close Docker Desktop completely, then delete:

bash
%AppData%\Docker\settings.json

Docker will recreate this file with default settings on next start. Your containers and images are preserved.

9Reinstall Docker Desktop (last resort)

If nothing else works:

1. Uninstall Docker Desktop from Windows Settings > Apps
2. Run wsl --unregister docker-desktop and wsl --unregister docker-desktop-data
3. Restart your computer
4. Download the latest Docker Desktop from https://www.docker.com/products/docker-desktop
5. Install using the default settings (do not use custom install location)

Advanced notes

VM Time Sync Issues: If Docker containers show incorrect time, run sudo hwclock -s inside WSL to sync the VM clock with the host.

Azure/AWS VMs: If running Docker Desktop in a cloud VM, you need nested virtualization support. This is only available on specific VM sizes (Dv3, Ev3 series on Azure) and regions.

Windows Insider/Preview builds: Newer Windows builds may break WSL compatibility temporarily. Check Docker's GitHub issues for known compatibility problems.

Alternative: If WSL 2 continues to cause issues, you can switch Docker Desktop to use the Hyper-V backend instead. Edit %AppData%\Docker\settings.json and set wslEngineEnabled to false. Note that Hyper-V backend has different performance characteristics and requires Hyper-V feature enabled.

Frequently asked questions

What does "Docker Desktop - Unexpected WSL error" mean?
Docker Desktop on Windows uses WSL 2 (Windows Subsystem for Linux) as its default backend for running Linux containers. When Docker starts, it creates two WSL distributions: 'docker-desktop' and 'docker-desktop-data'. The 'Unexpected WSL error' message indicates that Docker cannot properly initialize or communicate with these WSL distributions.
How do I fix "Docker Desktop - Unexpected WSL error"?
This error occurs when Docker Desktop fails to communicate with the Windows Subsystem for Linux (WSL 2) backend. It typically appears on Windows 10/11 when WSL components are misconfigured, outdated, or conflicting with other software like VPNs or Hyper-V settings.
What causes "Docker Desktop - Unexpected WSL error"?
Virtual Machine Platform Windows feature is not enabled Hyper-V hypervisor is disabled in boot configuration WSL 2 kernel is outdated and needs updating
Is the "Docker Desktop - Unexpected WSL error" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading