Local AI on Windows

12. WSL2 Troubleshooting

Chapter 12 of 15 · 20 min

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.

EXERCISE

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.