Troubleshooting

Try these in order when the Guide setup misbehaves. After changing .wslconfig or /etc/wsl.conf, always recycle the VM:

wsl --shutdown

Then open a new Ubuntu tab.

WSL will not install or start

• Confirm virtualization is on in firmware (Intel VT-x / AMD-V). Task Manager → Performance → CPU should say Virtualization: Enabled.
• Update WSL itself from PowerShell: wsl --update, then wsl --version.
• If wsl --install only prints help, WSL is already present — install a distro with wsl --list --online and wsl --install -d Ubuntu-24.04.
• "The virtual machine could not be started" after a Windows update: wsl --shutdown, reboot Windows, then wsl --update.

localhost does not reach the dev server

Mirrored networking (networkingMode=mirrored in .wslconfig) needs Windows 11 22H2+. Without it, NAT still forwards most WSL ports to Windows localhost, but VPNs and IPv6 often break.

1. Confirm the app is bound to 0.0.0.0 or localhost, not a stale Windows-only NIC.
2. Add or restore the .wslconfig snippet, then wsl --shutdown.
3. From PowerShell, wsl hostname -I shows the distro IP if you must hit it directly.

Installs and vite / nuxt are slow or miss file changes

The project is almost certainly under /mnt/c/.... Move it to ~/code in the Linux filesystem. Cross-OS I/O and Windows file watchers are the usual cause, not pnpm itself.

code: command not found

Install the WSL extension in Windows VS Code, then run code . once from Ubuntu. That installs the server and the code shim. If it still fails, in VS Code run WSL: Connect to WSL and open the folder from there.

A stuck "Installing VS Code Server" download: rm -rf ~/.vscode-server in Ubuntu and run code . again.

Git prompts for a password every time, or credential.helper is store

store writes ~/.git-credentials in plain text. Point the helper at Git Credential Manager instead — see Git. Confirm the .exe exists with where.exe git-credential-manager.exe.

Clock is wrong (TLS and gh auth fail)

WSL can drift after the laptop sleeps. In Ubuntu:

sudo hwclock -s

Or install systemd-timesyncd (systemd is on — see wsl.conf) and sudo timedatectl set-ntp true.

DNS or apt update fails on VPN

With mirrored networking, WSL should use the same DNS as Windows. If apt still cannot resolve hosts, /etc/wsl.conf can pin Windows DNS:

[network]
generateResolvConf = true

Then wsl --shutdown. Microsoft's WSL troubleshooting covers VPN-specific workarounds.

Ubuntu is using too much RAM

Cap it in %UserProfile%\.wslconfig (memory=8GB is a reasonable starting point on a 16 GB machine) and shut WSL down so the VM restarts.