Interactive Troubleshooter

Published: Oct 12, 2026

Docker Desktop WSL2 Engine Failed to Start - Kernel Version Tree

Time: 15 mins Level: Beginner

By StepDiag Engineering Team

Reviewed by Ibraheem Taofeeq Opeyemi

This interactive diagnostic tree resolves persistent 'WSL2 engine failed to start' and 'Docker Desktop stopped working' failures on Windows 10 and 11. It diagnoses outdated Linux kernel binaries, corrupted docker-desktop-data VHDX virtual disks, Virtual Machine Platform hypervisor locks, and Host Network Service (HNS) endpoints.

Full Diagnostic Tree & Step-by-Step Overview

What specific error dialog, popup code, or CLI error message does Docker Desktop exhibit during startup?

Popup states 'WSL 2 installation is incomplete' or 'The WSL 2 kernel package is required'.
Docker Desktop hangs on 'Starting the Docker Engine...' indefinitely or throws 'docker-desktop-data distro terminated unexpectedly'.
Error states 'Please enable the Virtual Machine Platform feature in Windows' or 'Hyper-V feature is disabled'.
Docker Engine fails during network initialization with 'HNS call failed' or 'An operation was attempted on something that is not a socket'.

What specific kernel or version discrepancy is preventing the WSL2 sub-system from mounting?

The WSL2 Linux kernel binary is missing or outdated (< 5.10.x), breaking container runtime system calls.
A custom .wslconfig file specifies an invalid kernel path or unsupported memory allocation.
WSL default version is forced to Version 1 instead of Version 2 across active distributions.
Windows build is below requirement (< Build 19041 for x64 or < Build 19042 for ARM64).

Updating WSL2 Linux Kernel Binary and Restarting Subsystem

Solution:

Root Cause: Outdated or Missing WSL2 Linux Kernel Package

Docker Desktop relies on a Microsoft-built Linux kernel (version 5.10+ or 6.x) running inside lightweight utility virtual machines managed by the Windows Subsystem for Linux (WSL2). If Windows was upgraded without fetching the standalone WSL kernel MSI package, or if Microsoft Update has not delivered the kernel payload, Docker Desktop cannot execute the containerd daemon because required cgroup v2 interfaces and eBPF kernel symbols are absent in legacy WSL binaries.

# Diagnostic Verification:

Open PowerShell as Administrator and query active kernel and WSL versions:

wsl --version

If output returns WSL version: 0.x or displays *'Command line option --version is not recognized'*, the system is running legacy WSL1 components or lacks the Microsoft Store/MSI kernel update payload.

# Step-by-Step Fix:

Force WSL Kernel Update via Windows CLI:

Open PowerShell as Administrator and execute:

wsl --update

If using an isolated or offline machine, download the official package directly from the Microsoft Official Support Guide or Microsoft Learn portal (wsl_update_x64.msi) and run the installer.

Force Complete WSL Shutdown:

Terminate all running Linux instances to unbind the old kernel binary:

wsl --shutdown

Verify Installed Kernel Version:

Run wsl --version again and confirm Kernel version is 5.10.102.1 or higher.

Relaunch Docker Desktop:

Open Docker Desktop and verify the status bar transitions to Engine Running.

# Prevention & Long-Term Monitoring:

Enable Receive updates for other Microsoft products under Windows Update > Advanced Options to ensure WSL kernel updates patch automatically.

Correcting Custom `.wslconfig` Parameter Misconfigurations

Solution:

Root Cause: Malformed `.wslconfig` Kernel Path or Memory Threshold Override

Power users frequently create a .wslconfig file in their user profile directory (%USERPROFILE%\.wslconfig) to constrain RAM usage or point to a custom Linux kernel build. If the path specified under kernel=C:\path\to\vmlinux contains backslash syntax errors, points to a deleted binary, or restricts memory (memory=512MB) below Docker's mandatory 2GB bootstrap threshold, the WSL2 hypervisor crashes during initialization, preventing Docker Engine from starting.

# Diagnostic Verification:

Check if a custom config file exists in PowerShell:

Test-Path "$env:USERPROFILE\.wslconfig"

View file contents:

Get-Content "$env:USERPROFILE\.wslconfig"

Look for invalid parameters, missing quotes, or restrictive memory / swap declarations.

# Step-by-Step Fix:

Rename or Remove Malformed Configuration File:

Open PowerShell and backup the existing config file:

Rename-Item -Path "$env:USERPROFILE\.wslconfig" -NewName "$env:USERPROFILE\.wslconfig.bak"

Create Valid Standard .wslconfig Template:

Re-create a clean .wslconfig in Notepad or PowerShell:

@"

[wsl2]

memory=4GB

processors=2

swap=2GB

localhostForwarding=true

"@ | Out-File -FilePath "$env:USERPROFILE\.wslconfig" -Encoding ascii

Restart WSL Subsystem:

Terminate active sessions in PowerShell:

wsl --shutdown

Restart Docker Desktop and monitor resource allocation.

# Prevention & Long-Term Monitoring:

Always validate custom Linux kernel path locations before adding kernel= lines to .wslconfig.

Enforcing WSL Version 2 for Docker Desktop Utility Distributions

Solution:

Root Cause: Distribution Version Set to Legacy WSL1

Docker Desktop deploys two dedicated, unmanaged Linux distributions: docker-desktop and docker-desktop-data. If global default WSL behavior was set to version 1 (wsl --set-default-version 1), or if an update downgraded these distributions, Docker Desktop fails to initialize because WSL1 lacks hypervisor-level container isolation, socket translation, and dynamic ext4 VHDX mounting mechanisms.

# Diagnostic Verification:

Open PowerShell and list all registered distributions along with their WSL architecture version:

wsl --list --verbose

Inspect the VERSION column for docker-desktop and docker-desktop-data. If either shows 1, version mismatch is confirmed.

# Step-by-Step Fix:

Force Global WSL Default Version to 2:

Open PowerShell as Administrator and run:

wsl --set-default-version 2

Convert Docker Distributions Explicitly to WSL2:

Convert docker-desktop:

wsl --set-version docker-desktop 2

Convert docker-desktop-data:

wsl --set-version docker-desktop-data 2

Terminate WSL Engine and Test:

Shut down WSL:

wsl --shutdown

Re-launch Docker Desktop.

# Prevention & Long-Term Monitoring:

Verify wsl -l -v after installing third-party Linux distributions to ensure default WSL2 enforcement remains intact.

Updating Windows OS Build to Meet Minimum WSL2 Hypervisor Requirements

Solution:

Root Cause: Deprecated Windows Operating System Build

WSL2 requires low-level kernel APIs (such as Hyper-V Host Compute Service v2 and lightweight utility VM primitives) introduced in Windows 10 Version 2004 (Build 19041) or higher for x64 systems, and Version 20H2 (Build 19042) for ARM64 systems. Attempting to run current Docker Desktop releases on older builds (e.g., Windows 10 Version 1909 or Enterprise LTSC 2019 Build 17763) results in silent startup failures or kernel entry point rejection.

# Diagnostic Verification:

Open Command Prompt or PowerShell and check exact OS build:

cmd.exe /c ver
Get-ItemProperty -Path "HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion" -Name CurrentBuildNumber, DisplayVersion

If CurrentBuildNumber is lower than 19041, the operating system cannot run Docker Desktop via WSL2 engine.

# Step-by-Step Fix:

Update Windows 10 / 11 via Windows Update:

Navigate to Settings > Update & Security > Windows Update.

Click Check for updates and install the latest Feature Update.

Perform In-Place OS Upgrade (Enterprise / LTSC Managed Hosts):

If Windows Update is managed by organizational WSUS, request upgrade to Windows 10/11 Enterprise 22H2 or Windows 11 LTSC 2024.

Verify WSL Capability Post-Update:

After rebooting, run wsl --install --no-distribution in PowerShell as Administrator.

# Prevention & Long-Term Monitoring:

Maintain Windows build targets on supported Semi-Annual Service channels to guarantee API compatibility with Docker Desktop.

What physical storage, Virtual Hard Disk (VHDX), or process lock issue is halting the `docker-desktop` distro?

The `docker-desktop-data` VHDX virtual disk file is corrupted or locked by a background process.
Disk space on drive C: is completely exhausted, preventing VHDX extension.
NTFS compressed or encrypted (EFS) folder flags on LocalAppData block VHDX attachment.
Stale `com.docker.service` or orphaned `wslhost.exe` process handles block engine boot.

Unregistering and Rebuilding Corrupted `docker-desktop-data` VHDX Instances

Solution:

Root Cause: Ext4 File System Corruption inside `ext4.vhdx` Storage Image

Docker Desktop stores all container images, volumes, and layer caches inside an ext4-formatted Virtual Hard Disk (ext4.vhdx) located under %LOCALAPPDATA%\Docker\wsl\data\ext4.vhdx. If the host workstation experiences an unexpected power loss, Blue Screen of Death (BSOD), or forced reboot while Docker Engine is writing to disk, the ext4 journal becomes unreadable. When WSL attempts to mount the image on startup, the operation times out, causing Docker Desktop to hang on *'Starting the Docker Engine...'*.

# Diagnostic Verification:

Open Event Viewer > Applications and Services Logs > Microsoft > Windows > Hyper-V-Storage > Admin.

Look for Event ID 27002 or error *'The virtual hard disk is corrupted or unreadable'* referencing ext4.vhdx.

# Step-by-Step Fix:

Terminate Docker and WSL Services:

Close Docker Desktop completely.

Open PowerShell as Administrator and run:

wsl --shutdown
taskkill /F /IM "com.docker.backend.exe" /T

Attempt VHDX Compaction and File System Check (Data Retention Fix):

Open PowerShell as Administrator and launch diskpart:

diskpart
select vdisk file="$env:LOCALAPPDATA\Docker\wsl\data\ext4.vhdx"
attach vdisk readonly
compact vdisk
detach vdisk
exit

Unregister and Reset Docker Distributions (Factory Reset Fix):

*Warning: Unregistering wipes local container layers and volumes; backup critical volumes beforehand if accessible.*

Run in PowerShell:

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

Relaunch Docker Desktop:

Open Docker Desktop. The application will detect missing distributions and automatically recreate fresh, healthy VHDX files.

# Prevention & Long-Term Monitoring:

Gracefully stop Docker Desktop before shutting down or putting the host Windows PC into sleep mode.

Shrinking Dynamic VHDX Disk Allocations and Freeing System Drive Storage

Solution:

Root Cause: Local Volume Capacity Exhaustion (0 Bytes Free on Host Drive)

WSL2 virtual hard disks dynamically expand up to a maximum default size of 1TB as containers write logs, build artifacts, and pull images. However, if the underlying host physical partition (typically C:\) drops below 1GB of free space, the Windows Hyper-V Storage VHDX provider refuses to allocate new block sectors. When Docker Engine starts up and attempts to write temporary runtime sockets to /var/run/docker.sock, the operation fails with ENOSPC (No space left on device).

# Diagnostic Verification:

Open PowerShell and check available space on drive C:

Get-PSDrive C | Select-Object Name, Used, Free

Attempting to start WSL returns: Error code: Wsl/Service/CreateInstance/CreateVm/0x80070070 *(ERROR_DISK_FULL)*.

# Step-by-Step Fix:

Prune Unused Docker System Artifacts:

If Docker CLI is partially responsive, run:

docker system prune -a --volumes -f

Compact VHDX Disk File Size in PowerShell:

Shut down WSL instances:

wsl --shutdown

Open PowerShell as Administrator and run diskpart:

diskpart
select vdisk file="$env:LOCALAPPDATA\Docker\wsl\data\ext4.vhdx"
compact vdisk
exit

Relocate Docker VHDX Storage Location to Secondary Drive (Permanent Fix):

Export data distro:

wsl --export docker-desktop-data D:\DockerData\docker-desktop-data.tar

Unregister original instance:

wsl --unregister docker-desktop-data

Import to target partition (e.g., D: drive):

wsl --import docker-desktop-data D:\DockerData\ $env:LOCALAPPDATA\Docker\wsl\data\docker-desktop-data.tar --version 2

Remove temporary .tar archive.

# Prevention & Long-Term Monitoring:

Configure automated docker image prune cron tasks or move the VHDX path to a dedicated, high-capacity secondary SSD.

Clearing NTFS Compression and Encrypting File System (EFS) Flags on VHDX Folders

Solution:

Root Cause: NTFS Compression or EFS Encryption Attributes on `%LOCALAPPDATA%`

To save disk space, users or automated Windows cleanup utilities sometimes apply system-wide NTFS Compression or Encrypting File System (EFS) attributes to the %LOCALAPPDATA% or AppData\Local\Docker directories. Hyper-V and WSL2 virtual disk drivers explicitly prohibit opening or attaching .vhdx storage blocks if the parent folder has the NTFS COMPRESSED or ENCRYPTED flag set, returning error code 0x800700c1 or failing silently.

# Diagnostic Verification:

Open PowerShell and inspect NTFS directory attributes for the Docker store:

Get-ItemProperty -Path "$env:LOCALAPPDATA\Docker\wsl" | Select-Object -ExpandProperty Attributes

If output includes Compressed or Encrypted, file allocation will fail.

# Step-by-Step Fix:

Strip NTFS Compression Flag via Compact CLI:

Open PowerShell as Administrator and run:

compact /u /s:"$env:LOCALAPPDATA\Docker\wsl" /i

Strip Attributes via GUI File Explorer:

Press Win + R, open %LOCALAPPDATA%\Docker.

Right-click the wsl folder > click Properties.

Click Advanced... under the General tab.

Uncheck Compress contents to save disk space and Encrypt contents to secure data.

Click OK > select Apply changes to this folder, subfolders and files.

Shutdown WSL and Restart Docker Desktop:

Execute wsl --shutdown in PowerShell and launch Docker Desktop.

# Prevention & Long-Term Monitoring:

Exclude %LOCALAPPDATA%\Docker\wsl from global disk compression software and automated optimization scripts.

Resetting Windows Docker Service and Clearing Orphaned `wslhost.exe` Handles

Solution:

Root Cause: Deadlocked Background Process Handles in `com.docker.service`

When Docker Desktop launches, it relies on a background Windows service (com.docker.service) to spawn inter-process communication (IPC) bridges with wslhost.exe and vmsrvc.exe. If Docker Desktop is closed and rapidly reopened, or if a Windows user session switches accounts, stale process handles hold IPC named pipe locks open (\\.\pipe\docker_engine), blocking new engine initialization.

# Diagnostic Verification:

Open PowerShell as Administrator and query running Docker process instances:

Get-Process -Name "com.docker*", "wslhost" -ErrorAction SilentlyContinue

If multiple wslhost.exe or com.docker.backend.exe processes remain active after closing Docker Desktop, deadlocked process state is confirmed.

# Step-by-Step Fix:

Stop Docker Desktop and Background Services:

Open PowerShell as Administrator and execute:

Stop-Service -Name "com.docker.service" -Force
taskkill /F /IM "docker.exe" /T -ErrorAction SilentlyContinue
taskkill /F /IM "Docker Desktop.exe" /T -ErrorAction SilentlyContinue
taskkill /F /IM "com.docker.backend.exe" /T -ErrorAction SilentlyContinue
taskkill /F /IM "wslhost.exe" /T -ErrorAction SilentlyContinue

Shutdown WSL Engine:

wsl --shutdown

Restart Service and Application:

Start-Service -Name "com.docker.service"

Open Docker Desktop from the Start Menu.

# Prevention & Long-Term Monitoring:

Allow 10-15 seconds for background processes to terminate cleanly when quitting Docker Desktop.

Which hypervisor feature, virtualization setting, or BIOS security policy is disabled?

Virtual Machine Platform / Hyper-V optional features are disabled in Windows.
Hardware Virtualization (Intel VT-x / AMD-V) is turned off in system BIOS/UEFI firmware.
Hypervisor launch type is set to 'Off' in Windows Boot Configuration Data (BCD).
Nested Virtualization is disabled on virtual machine guests running Docker Desktop.

Enabling Windows Virtual Machine Platform and Hyper-V Features via DISM

Solution:

Root Cause: Uninstalled Virtual Machine Platform / Windows Subsystem for Linux Features

WSL2 operates by running a lightweight Linux VM inside a specialized Virtualization Infrastructure layer called Virtual Machine Platform. Unlike traditional Hyper-V, Virtual Machine Platform does not require the full Hyper-V Management Tools role on Windows 10/11 Home editions. However, if this underlying feature or the Microsoft-Windows-Subsystem-Linux feature is disabled or turned off after a Windows update reset, WSL2 cannot request hypervisor contexts.

# Diagnostic Verification:

Open PowerShell as Administrator and query feature deployment status:

Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform, Microsoft-Windows-Subsystem-Linux

If State displays Disabled for either feature, WSL2 engines cannot boot.

# Step-by-Step Fix:

Enable Virtual Machine Platform via DISM in PowerShell:

Open PowerShell as Administrator and run:

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

Enable Hyper-V Feature Set (Windows Pro / Enterprise / Education):

dism.exe /online /enable-feature /featurename:Microsoft-Hyper-V /all /norestart

Reboot Computer:

Perform a full cold reboot (shutdown /r /t 0) to allow Windows Servicing to inject hypervisor drivers at boot.

# Prevention & Long-Term Monitoring:

Verify feature state prior to deploying Docker Desktop on clean corporate desktop images.

Enabling Hardware Virtualization (Intel VT-x / AMD-V) in System BIOS/UEFI

Solution:

Root Cause: CPU Virtualization Extensions Disabled in System Motherboard Firmware

WSL2 relies on hardware-assisted CPU virtualization extensions—Intel VT-x / VMX or AMD-V / SVM. If these extensions are disabled inside the computer's BIOS/UEFI setup menu, or if a firmware reset/CMOS battery clear reset settings to default, the Windows hypervisor cannot initialize hardware-assisted paging tables (SLAT/EPT). WSL displays error 0x80370102 (*'Please enable the Virtual Machine Platform feature in Windows and ensure virtualization is enabled in the BIOS'*).

# Diagnostic Verification:

Open PowerShell and check CPU Virtualization state reported by the OS:

Get-CimInstance -ClassName Win32_Processor | Select-Object Name, VirtualizationFirmwareEnabled

Alternatively, open Task Manager (Ctrl + Shift + Esc) > Performance tab > CPU. Look for Virtualization: Disabled.

# Step-by-Step Fix:

Enter BIOS/UEFI Setup Utility:

Reboot the PC and press the dedicated BIOS setup key during POST screen (F2, Del, or F10).

*(Alternatively, navigate to Windows Settings > Recovery > Advanced Startup > Restart now > Troubleshoot > Advanced options > UEFI Firmware Settings).*

Enable CPU Virtualization Features:

For Intel CPUs: Locate Intel Virtualization Technology, Intel VT-x, or Vanderpool and set to Enabled.

For AMD CPUs: Locate SVM Mode, AMD-V, or Secure Virtual Machine and set to Enabled.

Ensure IOMMU / Intel VT-d is also toggled to Enabled.

Save Changes and Exit:

Press F10 to save configurations and boot into Windows.

Verify Task Manager shows Virtualization: Enabled.

# Prevention & Long-Term Monitoring:

Re-check BIOS settings after updating motherboard firmware versions.

Configuring Boot Configuration Data (`hypervisorlaunchtype Auto`) Flags

Solution:

Root Cause: Windows Hypervisor Loader Disabled in Boot Manager (BCD)

Certain third-party virtualization products (such as legacy VMware Workstation builds or VirtualBox 5.x) or aggressive security hardening scripts modify the Windows Boot Configuration Data (BCD) store by explicitly setting hypervisorlaunchtype to Off. This forces the Windows boot loader to start the OS kernel without loading the Windows Hypervisor (hvloader.dll), making it impossible for WSL2 or Docker Desktop to run.

# Diagnostic Verification:

Open Command Prompt as Administrator and query BCD configuration:

bcdedit /enum {current}

Inspect the setting for hypervisorlaunchtype. If it displays Off, the hypervisor is blocked at boot time.

# Step-by-Step Fix:

Set BCD Hypervisor Launch Type to Automatic:

Open Command Prompt as Administrator and run:

bcdedit /set hypervisorlaunchtype auto

Verify Settings Update:

Re-run bcdedit /enum {current} and confirm hypervisorlaunchtype is set to Auto.

Perform System Cold Restart:

Reboot the workstation (shutdown /r /t 0) to initialize the Windows Hypervisor layer.

# Prevention & Long-Term Monitoring:

Avoid running unverified OS tweaking utilities that alter low-level Windows BCD boot flags.

Enabling Nested Virtualization on Hyper-V / VMware Guest VM Environments

Solution:

Root Cause: Disabled Nested Virtualization on Cloud or On-Premise Virtual Machines

When running Docker Desktop inside a virtual machine (e.g., an Azure VM, AWS EC2 instance, or Hyper-V / VMware guest), the parent hypervisor must pass hardware virtualization extensions down into the guest VM layer—a feature known as Nested Virtualization. If nested virtualization is omitted on the host hypervisor settings, WSL2 inside the guest VM cannot access CPU VMX/SVM flags, blocking Docker Desktop startup.

# Diagnostic Verification:

Inside the guest VM, open PowerShell as Administrator and run:

Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform

Attempting to run wsl returns: Error: 0x80370102 despite BIOS showing virtualization enabled.

# Step-by-Step Fix:

Enable Nested Virtualization on Parent Hyper-V Host (For Hyper-V Guests):

Shut down the target VM on the physical Hyper-V host.

Open PowerShell as Administrator on the Host and run:

Set-VMProcessor -VMName "YourDockerVMName" -ExposeVirtualizationExtensions $true

Enable Nested Virtualization on VMware ESXi / Workstation:

Edit VM Settings in VMware vSphere Client.

Expand CPU settings > check Expose hardware assisted virtualization to the guest OS.

Enable Nested Virtualization in Cloud Platforms:

Choose instance sizes that natively support nested virtualization (e.g., Azure Dv3/Ev3 series or AWS metal/nitro instances).

Boot Guest VM and start Docker Desktop.

# Prevention & Long-Term Monitoring:

Verify VM instance type compatibility before deploying containerized developer images in cloud desktop environments.

What Windows networking service, socket binding, or VPN driver conflict is blocking container bridges?

Host Network Service (HNS) or WinNAT driver failed to allocate the internal container subnet.
WSA / WinSock port exclusion range blocks Docker API communication on local TCP ports.
Third-party VPN or Endpoint Security software blocks WSL2 virtual Ethernet adapter packets.
Windows Firewall blocks inbound/outbound traffic across the `vEthernet (WSL)` virtual switch.

Resetting Host Network Service (HNS) and Clearing Stale Container Endpoints

Solution:

Root Cause: Host Network Service (HNS) Endpoint Deadlock

The Windows Host Network Service (HNS) manages virtual networks, NAT tables, and switch ports for both Windows containers and WSL2 utility VMs. When Docker Desktop boots, it requests HNS to instantiate a virtual network switch. If legacy network endpoints or stale NAT bindings persist following an improper network disconnection, HNS rejects new allocation requests, returning HNS call failed or 0x8007003b.

# Diagnostic Verification:

Open PowerShell as Administrator and inspect HNS network states:

Get-HnsNetwork

If errors appear or if phantom networks remain allocated while WSL is stopped, HNS state corruption is confirmed.

# Step-by-Step Fix:

Stop Docker and Shutdown WSL:

Open PowerShell as Administrator and run:

wsl --shutdown
Stop-Service -Name "com.docker.service" -Force

Restart Host Network Service and Clear Endpoints:

Stop the service:

Stop-Service -Name hns -Force

Delete stale HNS network definitions using PowerShell:

Get-HnsNetwork | Remove-HnsNetwork -Force

Restart the service:

Start-Service -Name hns
Start-Service -Name winnat

Restart Docker Background Service:

Start-Service -Name "com.docker.service"

Open Docker Desktop and verify engine startup.

# Prevention & Long-Term Monitoring:

Avoid toggling Windows network adapter settings or changing VPN connections while Docker containers are actively building.

Resetting WinSock Catalog and Reserved TCP Dynamic Port Exclusions

Solution:

Root Cause: WinSock Port Reservation Overlap with Docker Daemon Ports

Windows Hyper-V and NAT services dynamically reserve ranges of ephemeral TCP ports for internal utility routing upon boot. Occasionally, Windows administrative updates or Hyper-V port allocation reserve the specific local ports needed by Docker Desktop (such as port 2375, 2376, or internal IPC control ports). When Docker attempts to bind its local API socket, Windows denies access with An operation was attempted on something that is not a socket or Access Denied.

# Diagnostic Verification:

Open Command Prompt as Administrator and list excluded port ranges:

netsh interface ipv4 show excludedportrange protocol=tcp

Check if standard developer ports or Docker IPC ports fall inside these wildcard reserved ranges.

# Step-by-Step Fix:

Reset Windows Sockets (WinSock) Catalog:

Open Command Prompt as Administrator and run:

netsh winsock reset
netsh int ip reset

Restrict Dynamic Hyper-V Port Reservation Window:

Re-configure the OS dynamic port start range so it does not collide with Docker dev ports:

netsh int ipv4 set dynamicport tcp start=49152 num=16384

Reboot Workstation:

Restart Windows (shutdown /r /t 0) to apply the newly defined dynamic socket boundaries.

# Prevention & Long-Term Monitoring:

Reserve critical development ports explicitly using netsh int ipv4 add excludedportrange if port conflict recurs.

Configuring VPN Split-Tunneling and Network Interface Metric Prioritization

Solution:

Root Cause: Corporate VPN Adapter Route Hijacking (`vEthernet (WSL)` Interception)

Enterprise VPN clients (such as Cisco AnyConnect, Palo Alto GlobalProtect, or Fortinet) often enforce strict full-tunnel routing rules. Upon connection, the VPN driver injects a default route metric (0.0.0.0/0) that overrides all local interface routes, including the internal Hyper-V virtual switch adapter (vEthernet (WSL) / 172.x.x.x). Packets sent between the Windows host and the Docker Desktop WSL2 daemon are redirected into the remote VPN tunnel, breaking inter-process communication.

# Diagnostic Verification:

Docker Desktop functions normally when disconnected from VPN, but fails or loses daemon connectivity immediately after connecting to corporate VPN.

# Step-by-Step Fix:

Enable WSL2 Mirrored Networking Mode (Windows 11 23H2+ / WSL 2.0+):

Open PowerShell and update .wslconfig to use native networking mode that integrates seamlessly with VPN adapters:

@"

[wsl2]

networkingMode=mirrored

dnsTunneling=true

autoProxy=true

"@ | Out-File -FilePath "$env:USERPROFILE\.wslconfig" -Encoding ascii

Adjust Route Metrics for WSL Virtual Adapter (Windows 10 / Older Builds):

Open PowerShell as Administrator and force lower priority on the WSL adapter:

Set-NetIPInterface -InterfaceAlias "vEthernet (WSL)" -InterfaceMetric 6000

Restart WSL Subsystem:

wsl --shutdown

Relaunch Docker Desktop.

# Prevention & Long-Term Monitoring:

Request corporate IT network teams to add the WSL2 subnet range (172.16.0.0/12) to the VPN split-tunneling exclusion list.

Configuring Windows Defender Firewall Rules for WSL Virtual Switch

Solution:

Root Cause: Host Firewall Block on WSL Inter-Process Traffic

Windows Defender Firewall or third-party endpoint security firewalls treat the vEthernet (WSL) interface as an unidentified public network. If restrictive firewall policies block inbound traffic on public profiles, the host blocks all incoming TCP/UDP connections originated by the Docker daemon running inside the WSL2 Linux guest back to the Windows host bridge.

# Diagnostic Verification:

Open PowerShell as Administrator and query network connection profile for the WSL adapter:

Get-NetConnectionProfile -InterfaceAlias "vEthernet (WSL)"

If NetworkCategory returns Public, firewall rules may be blocking socket traffic.

# Step-by-Step Fix:

Reassign WSL Network Category to Private:

Open PowerShell as Administrator and run:

Set-NetConnectionProfile -InterfaceAlias "vEthernet (WSL)" -NetworkCategory Private

Create Windows Firewall Allow Rules for Docker Desktop Executables:

Run administrative PowerShell commands:

New-NetFirewallRule -DisplayName "Docker Desktop Backend" -Direction Inbound -Program "C:\Program Files\Docker\Docker\resources\com.docker.backend.exe" -Action Allow -Profile Any

New-NetFirewallRule -DisplayName "WSL Traffic Allow" -Direction Inbound -InterfaceAlias "vEthernet (WSL)" -Action Allow

Restart Docker Desktop and verify engine state.

# Prevention & Long-Term Monitoring:

Ensure endpoint protection suites maintain exclusions for official Docker Desktop executables and virtual switch interfaces.

Related Diagnostic Guides

Fix Copy text (Ctrl-C or context menu) not working on browsers

Windows Credential Guard Blocking App Exclusions: How to Fix It

WordPress Redirecting to Spam Websites: How to Fix It

Malicious Browser Extensions: How to Detect and Remove Them

Unreal Engine Shader Compilation Stuttering: How to Fix It

Subscribe to StepDiag

Embed Guide on Your Website