---
title: "Troubleshooting"
description: "Fixes for WSL that will not start, slow installs, localhost mismatches, and a missing code command."
canonical_url: "https://vinicunca.dev/windows-dev/extras/troubleshooting"
---
# Troubleshooting

> Fixes for WSL that will not start, slow installs, localhost mismatches, and a missing code command.

Try these in order when the [Guide](https://vinicunca.dev/windows-dev/guide) setup misbehaves. After changing `.wslconfig` or `/etc/wsl.conf`, always recycle the VM:

```powershell
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](https://vinicunca.dev/windows-dev/guide/wsl#global-settings-wslconfig), 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](https://vinicunca.dev/windows-dev/guide/git#git-credential-manager). 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:

```bash
sudo hwclock -s
```

Or install `systemd-timesyncd` (systemd is on — see [wsl.conf](https://vinicunca.dev/windows-dev/guide/wsl#per-distribution-settings-etcwslconf)) 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:

```ini [/etc/wsl.conf]
[network]
generateResolvConf = true
```

Then `wsl --shutdown`. Microsoft's [WSL troubleshooting](https://learn.microsoft.com/en-us/windows/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.

---

- [WSL troubleshooting](https://learn.microsoft.com/en-us/windows/wsl/troubleshooting)


## Sitemap

See the full [sitemap](https://vinicunca.dev/sitemap.md) for all pages.