12. WSL2 Troubleshooting
WSL2 failures fall into four categories: installation failures, network failures, GPU failures, and storage failures. Here are the specific symptoms and fixes for each.
Installation failures:
Error: WslRegisterDistribution failed with error: 0x800701bc
Fix: Update WSL2 kernel. In elevated PowerShell: wsl --update. If that fails, download the MSI manually from Microsoft's catalog and run msiexec /i wsl_update_x64.msi.
Error: The operation timed out
Fix: WSL2 install fails on metered connections or VPNs. Disconnect VPN, set network to "Metered: No" in Settings, retry. Alternatively: wsl --install --web-download forces a different download method.
Network failures:
WSL2 loses internet access after resume from sleep or after wsl --shutdown and restart. Check with:
ping 8.8.8.8
If ping works but DNS fails:
ping google.com
If DNS fails, restart the WSL2 networking service:
sudo /etc/init.d/resolvconf restart
Or regenerate the DNS configuration:
echo "[network]" | sudo tee /etc/wsl.conf
echo "generateResolvConf = false" | sudo tee -a /etc/wsl.conf
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
Rebuild the .wslconfig with wsl --shutdown and reopen.
GPU failures:
nvidia-smi works on Windows but not inside WSL2. Reinstall the WSL2-specific NVIDIA driver. The driver version for WSL2 (e.g., 536.67) differs from the Windows display driver (e.g., 552.22).
Storage failures:
Error: WSL2 has exhausted its maximum internal storage size
Fix: Compact the WSL2 virtual disk:
wsl --shutdown
diskpart
# In diskpart:
select vdisk file="C:\Users\YOUR_USERNAME\AppData\Local\wsl\ext4.vhdx"
attach vdisk readonly
compact vdisk
detach vdisk
exit
Then expand the WSL2 filesystem inside Ubuntu:
sudo resize2fs /dev/sdb 50G
Local verification checkpoint
Run the smallest example from this chapter in a local workspace and record the package version, runtime, data path, and observed output. If the result depends on model size, vector count, CPU/GPU backend, or available memory, note that constraint beside the exercise so the lesson remains reproducible.
Introduce a deliberate network failure inside WSL2 (sudo ip link delete eth0), confirm connectivity breaks, then restore it using the resolv.conf method above and verify with ping google.com.