WSL Common Errors — Windows Subsystem for Linux Troubleshooting
About WSL Common Errors
Fix common WSL (Windows Subsystem for Linux) errors including installation failures, networking issues, file system access errors, and WSL2 VM startup failures. This guide covers everything you need to know about this topic, including common causes, step-by-step solutions, and answers to frequently asked questions.
Here are the key things to understand: WSL2 runs a real Linux kernel in a lightweight Hyper-V virtual machine. Common error: 'WslRegisterDistribution failed with error: 0x80370102' — virtualization not enabled. WSL2 requires: Windows 10 2004+, Virtual Machine Platform, and BIOS virtualization (VT-x/AMD-V). File system access between Windows and WSL has performance implications (/mnt/c/ is slower). WSL networking uses a virtual NAT network — localhost port forwarding may not work as expected. Understanding these fundamentals will help you diagnose and resolve this issue more effectively.
The most common reasons this occurs include: Virtualization not enabled in BIOS/UEFI settings. Virtual Machine Platform Windows feature not installed. Hyper-V conflicting with other virtualization software (VirtualBox, VMware). WSL2 kernel update not installed. Insufficient disk space for WSL2 virtual hard disk. Identifying the root cause is the first step toward finding the right solution.
To resolve this, follow these recommended steps: Enable virtualization in BIOS: restart, enter BIOS, enable Intel VT-x or AMD-V. Install required features: wsl --install (Windows 11) or enable 'Virtual Machine Platform' in Windows Features. Update WSL: wsl --update from PowerShell (Administrator). Reset a broken WSL distro: wsl --unregister <distro> then reinstall from Microsoft Store. Fix networking: wsl --shutdown then restart WSL to reset the network adapter. Set WSL2 as default: wsl --set-default-version 2. If these steps do not resolve the issue, consider consulting additional resources or a qualified professional.
This article is part of our Windows Error Codes collection on Error Codes Wiki. We provide comprehensive, up-to-date information to help you find solutions quickly.
Quick Answer
What is the difference between WSL1 and WSL2?
WSL1 translates Linux syscalls to Windows kernel calls. WSL2 runs a full Linux kernel in a VM. WSL2 has better compatibility and filesystem performance for Linux files.
Overview
Fix common WSL (Windows Subsystem for Linux) errors including installation failures, networking issues, file system access errors, and WSL2 VM startup failures.
Key Details
- WSL2 runs a real Linux kernel in a lightweight Hyper-V virtual machine
- Common error: 'WslRegisterDistribution failed with error: 0x80370102' — virtualization not enabled
- WSL2 requires: Windows 10 2004+, Virtual Machine Platform, and BIOS virtualization (VT-x/AMD-V)
- File system access between Windows and WSL has performance implications (/mnt/c/ is slower)
- WSL networking uses a virtual NAT network — localhost port forwarding may not work as expected
Common Causes
- Virtualization not enabled in BIOS/UEFI settings
- Virtual Machine Platform Windows feature not installed
- Hyper-V conflicting with other virtualization software (VirtualBox, VMware)
- WSL2 kernel update not installed
- Insufficient disk space for WSL2 virtual hard disk
Steps
- 1Enable virtualization in BIOS: restart, enter BIOS, enable Intel VT-x or AMD-V
- 2Install required features: wsl --install (Windows 11) or enable 'Virtual Machine Platform' in Windows Features
- 3Update WSL: wsl --update from PowerShell (Administrator)
- 4Reset a broken WSL distro: wsl --unregister <distro> then reinstall from Microsoft Store
- 5Fix networking: wsl --shutdown then restart WSL to reset the network adapter
- 6Set WSL2 as default: wsl --set-default-version 2