Fix a problem

Phone cannot reach the dev server#

Your phone on the same Wi-Fi times out opening a dev server or Expo/Metro running in WSL. Find which hop blocks it.

Symptoms#

• The page works on the PC (localhost:5173) but the phone times out or shows “connection refused”.
• Expo Go spins on “Opening project…” or reports it could not connect to Metro on port 8081.

A request from the phone has to pass four hops: the Wi-Fi network, the Windows firewall, WSL’s network mode, and the dev server’s bind address. Check them from the inside out.

Diagnose#

1. Is the server listening on all interfaces, not just loopback?

   ss -ltn 'sport = :5173'      # 0.0.0.0 or [::] = reachable; 127.0.0.1 = this machine only

2. Which networking mode is WSL in?

   wslinfo --networking-mode       # recent WSL; otherwise compare `ip -br addr` with Windows ipconfig

3. Which IP should the phone use? It is the Windows Wi-Fi adapter’s IPv4 address:

   ipconfig | Select-String IPv4

4. Is there a Hyper-V firewall rule for the port?

   Get-NetFirewallHyperVRule | Where-Object Direction -eq Inbound |
     Select-Object Name, DisplayName, LocalPorts, Action

5. Is the phone really on the same network? Guest networks and many office or hotel Wi-Fis use client isolation: devices cannot see each other at all.

Fix#

Verify#

From the phone’s browser, open http://192.168.1.50:5173 (your IP and port). The page loads, and saving a file reloads it on the phone too.

A port is already in use#

Find what is using port 3000 (or any port), on the Linux side or the Windows side, and free it without restarting everything.

Symptoms#

• Error: listen EADDRINUSE: address already in use :::3000
• Port 3000 is in use, trying another one… (Vite, Next.js)
• bind: address already in use from Docker or a database
• An An attempt was made to access a socket in a way forbidden by its access permissions error on Windows, even though nothing seems to be listening

Diagnose#

Replace 3000 with your port in every command.

1. Is something inside WSL listening on it?

   ss -ltnp 'sport = :3000'
   sudo lsof -iTCP:3000 -sTCP:LISTEN     # shows processes of other users too

2. Is it a container?

   docker ps --filter publish=3000

3. Is something on Windows listening on it?

   Get-NetTCPConnection -LocalPort 3000 -State Listen -EA 0 |
     Select-Object LocalAddress, OwningProcess, @{n='Process';e={(Get-Process -Id $_.OwningProcess).ProcessName}}

4. Nothing found in 1–3? Check whether Windows has reserved the port:

   netsh interface ipv4 show excludedportrange protocol=tcp

Fix#

kill <pid>          # polite; use kill -9 <pid> only if it ignores this

wsl --shutdown
net stop winnat
net start winnat

Verify#

Run the diagnosis commands again: they return nothing for the port, and your server starts without EADDRINUSE.

DNS fails after connecting to a VPN#

Names stop resolving inside WSL (but work in Windows) once a corporate VPN connects. Confirm it is DNS, then let WSL use Windows' resolver.

Symptoms#

• curl: (6) Could not resolve host: github.com
• Temporary failure in name resolution from apt, git or npm
• It starts when the VPN connects; Windows apps keep working.

Diagnose#

1. Is it DNS, or the whole connection? Compare a name with a bare IP:

   getent hosts github.com            # no output = DNS fails
   curl -sI https://1.1.1.1 | head -1 # a response = the network itself works

2. Does Windows resolve the same name?

   Resolve-DnsName github.com

3. What is WSL using as its resolver?

   cat /etc/resolv.conf
   grep -iE 'dnsTunneling|autoProxy|networkingMode' /mnt/c/Users/*/.wslconfig 2>/dev/null

Fix#

[wsl2]
dnsTunneling=true
autoProxy=true        # also pick up the VPN's proxy settings

[network]
generateResolvConf=false

sudo rm /etc/resolv.conf      # it is a symlink WSL created
printf 'nameserver 172.16.0.53\nnameserver 1.1.1.1\n' | sudo tee /etc/resolv.conf

Verify#

With the VPN connected, getent hosts github.com prints an address and git fetch works.

Docker cannot reach my local API#

A container gets "connection refused" or a timeout calling an API or database that runs directly in WSL. Find out where the request goes.

Symptoms#

• ECONNREFUSED 127.0.0.1:4000 or connect ECONNREFUSED ::1:4000 from inside a container
• getaddrinfo ENOTFOUND host.docker.internal
• The same URL works with curl from the WSL shell.

Inside a container, localhost is the container itself, not WSL. The container has to reach the WSL host through another address, and the API has to accept connections on it.

Diagnose#

1. Which Docker are you using? Docker Engine inside WSL and Docker Desktop behave differently.

   docker info --format '{{.OperatingSystem}}'   # "Docker Desktop" or your Ubuntu version

2. What address does the API listen on?

   ss -ltn 'sport = :4000'     # 127.0.0.1 = WSL only; 0.0.0.0 or [::] = also containers

3. What does the container actually resolve and reach?

   docker compose exec app getent hosts host.docker.internal
   docker compose exec app wget -qO- http://host.docker.internal:4000/health   # or curl, if the image has it

Fix#

Verify#

The wget (or curl) from step 3 returns your API’s response, and the app in the container stops logging connection errors.

adb devices shows nothing in WSL#

The Android emulator or a USB phone shows up on Windows but adb inside WSL lists no devices, or fights the Windows adb server.

Symptoms#

• adb devices in WSL prints List of devices attached and nothing else.
• adb server version (41) doesn't match this client (39); killing... and the emulator disconnects on Windows.
• npx expo run:android or react-native run-android cannot find a device.

WSL cannot see USB devices or the Windows emulator directly. The setup in Run Android builds against the Windows emulator makes WSL’s adb talk to the Windows adb server instead.

Diagnose#

1. Does Windows see the device?

   adb devices

2. Is WSL pointed at the Windows server, and can it reach it?

   echo $ADB_SERVER_SOCKET          # expect tcp:127.0.0.1:5037
   adb version
   adb devices

3. Networking mode: reaching 127.0.0.1:5037 on Windows from WSL needs mirrored networking.

Fix#

Verify#

adb devices in WSL lists the same device as on Windows, and the emulator stays connected in Android Studio.

Changes do not trigger hot reload#

You save a file and the dev server or test watcher does not notice. Usually the project lives on /mnt/c, or Linux ran out of file watchers.

Symptoms#

• Saving a file does not refresh the browser or rebuild.
• Error: ENOSPC: System limit for number of file watchers reached
• Watchers work in a small project but not in the monorepo.

Linux tools learn about file changes through inotify. It only works reliably for files on the Linux disk, and the number of watched files is capped.

Diagnose#

1. Where is the project?

   pwd          # starts with /mnt/c/… = on the Windows drive

2. How many watchers are allowed, and is the error in the dev server output?

   cat /proc/sys/fs/inotify/max_user_watches /proc/sys/fs/inotify/max_user_instances

3. How was the editor opened? The status bar should say WSL: Ubuntu. Opening \\wsl.localhost\… paths directly from a Windows editor bypasses the WSL integration.

Fix#

mkdir -p ~/dev && cd ~/dev
git clone <repo-url>

Verify#

Save a file: the terminal logs a rebuild or HMR update within a second, and the browser updates without a manual refresh.

Builds and installs are slow#

npm/pnpm install, builds, git status or tests take much longer in WSL than they should. Measure first, then fix the actual bottleneck.

Symptoms#

• pnpm install or npm ci takes minutes for a project that installs in seconds elsewhere.
• git status pauses noticeably in a mid-size repo.
• Builds or test runs are several times slower than on a teammate’s machine.

Diagnose#

1. Where is the project, and which tools are running?

   pwd                       # /mnt/c/… = Windows drive
   which node npm pnpm git   # any /mnt/c/… path = a Windows binary

2. Is Linux short of memory and swapping?

   free -h
   vmstat 2 5                # non-zero "si"/"so" columns = swapping

3. Is Windows Defender scanning heavily? Open Task Manager during the build and look for high CPU in Antimalware Service Executable (MsMpEng.exe).

4. Time the slow step so you can compare after the fix:

   time pnpm install --frozen-lockfile

Fix#

Verify#

Repeat the timed command from step 4. Note both times; if it is still slow after moving the project, work through the remaining findings one by one so you know which change helped.

Too many open files#

A dev server, test runner or database fails with EMFILE because it hit the per-process open file limit.

Symptoms#

• Error: EMFILE: too many open files, watch or …, open '…'
• accept: too many open files from a server
• Different from ENOSPC … file watchers (that is hot reload).

Diagnose#

1. What limits does your shell have?

   ulimit -Sn; ulimit -Hn

2. For a service started by systemd (Docker, databases), check the service’s own limit:

   systemctl show docker -p LimitNOFILE

3. How many files does the failing process hold? While it runs:

   ls /proc/<pid>/fd | wc -l

Fix#

Verify#

Open a new terminal: ulimit -Sn shows the new value, and the failing command runs without EMFILE.

WSL uses too much memory#

Task Manager shows VmmemWSL holding many gigabytes, and Windows gets slow. Find out whether it is real usage or Linux cache.

Symptoms#

• Task Manager shows VmmemWSL (or Vmmem) using 8, 16 GB or more.
• Windows apps slow down or start swapping while WSL is open.
• Memory does not go down after you stop your dev servers.

Diagnose#

1. How much of WSL’s memory is actually used by processes, and how much is cache?

   free -h     # "used" = processes; "buff/cache" = file cache Linux can drop

2. Which processes use the most?

   ps aux --sort=-%mem | head -n 8
   docker stats --no-stream 2>/dev/null

3. Is there a cap in .wslconfig? Without one, WSL may grow to half your RAM (more on some versions).

   Get-Content $env:USERPROFILE\.wslconfig -EA 0

Fix#

Verify#

After the change (and a wsl --shutdown if you edited .wslconfig), free -h in WSL shows the new total, and VmmemWSL in Task Manager drops back after builds finish.

Windows disk space is running out#

C: is filling up and WSL is the suspect. Measure the virtual disk and what is inside it before deleting anything.

Symptoms#

• Windows warns that C: is low on space.
• The WSL virtual disk (ext4.vhdx) is much larger than what df shows as used inside Linux.
• Docker images and build cache keep piling up.

Your whole distro lives in one file, ext4.vhdx. It grows as you write, and by default does not shrink when you delete files inside Linux.

Diagnose#

1. How big is the virtual disk on Windows?

   Get-ChildItem "$env:LOCALAPPDATA\wsl", "$env:LOCALAPPDATA\Packages\CanonicalGroupLimited.*" -Recurse -Filter ext4.vhdx -EA 0 |
     Select-Object FullName, @{n='GB';e={[math]::Round($_.Length/1GB,1)}}

2. How much does Linux actually use?

   df -h /

3. Where is it going?

   sudo du -xh --max-depth=1 / 2>/dev/null | sort -h | tail -n 8
   du -h --max-depth=1 ~ 2>/dev/null | sort -h | tail -n 8
   docker system df

Fix#

Verify#

Repeat step 1 after shrinking: the vhdx size is close to df’s used space, and Windows shows the space as free.

Not sure what is wrong? Run a health check#

A two-minute check of WSL, systemd, networking and Docker after an update or a config change. Each result links to the matching fix.

Symptoms#

Something feels off after an update, a reboot or a change to .wslconfig / wsl.conf, and you do not yet know what. Start here; every check is read-only.

Diagnose#

1. WSL itself, from PowerShell:

   wsl --version          # WSL and kernel versions
   wsl -l -v              # distros, state, and VERSION 2

2. Inside Ubuntu:

   free -h && nproc                  # matches memory= and processors= in .wslconfig?
   systemctl is-system-running       # "running", not "degraded"
   systemctl --failed
   ip -br addr                       # mirrored mode: same IPs as Windows
   getent hosts github.com           # DNS works
   docker ps                         # works without sudo (if you use Docker)

Fix#

Verify#

Every line above gives the expected result. Keep this page bookmarked for the next WSL update.

.wslconfig changes do nothing#

You edited %USERPROFILE%\.wslconfig but memory, networking or other settings did not change. Check the file name, the restart, and the key.

Symptoms#

• free -h still shows the old memory size after you changed memory=.
• Mirrored networking, DNS tunneling or another key seems to have no effect.

Diagnose#

1. Is the file really named .wslconfig, in your Windows user folder?

   Get-ChildItem $env:USERPROFILE -Force -Filter '.wslconfig*' | Select-Object Name, Length, LastWriteTime

2. Did WSL fully stop since you edited it? Closing terminal tabs is not enough.

   wsl -l --running

3. Does WSL accept the key? Open WSL Settings from the Start menu: it is a GUI over this file and only shows keys your WSL version supports. Unknown or misspelled keys are ignored (recent versions print a warning when WSL starts).

Fix#

wsl --shutdown

Verify#

After reopening Ubuntu, the setting shows up: free -h reports the new memory total, nproc the new CPU count, and mirrored mode shows the same IPs as Windows in ip -br addr.

systemctl says degraded#

systemctl is-system-running reports degraded. Find the failed unit; on WSL it is usually systemd-binfmt, which is safe to mask.

Symptoms#

systemctl is-system-running prints degraded instead of running. Services may still work, but tools that wait for a healthy system can hang or complain.

Diagnose#

systemctl --failed
journalctl -b -u systemd-binfmt.service --no-pager | tail -n 5   # if it is listed

Fix#

sudo systemctl mask systemd-binfmt.service

Verify#

Run wsl --shutdown in PowerShell, reopen Ubuntu, wait a few seconds, then systemctl is-system-running prints running.

Clock is wrong after sleep#

After the PC sleeps, WSL's clock lags behind Windows, causing TLS errors, failed apt updates or expired tokens.

Symptoms#

• Release file … is not valid yet from apt update
• TLS or certificate errors such as certificate is not yet valid
• Signed URLs, OTP codes or tokens are rejected as expired

Diagnose#

Compare the clocks:

date
powershell.exe -NoProfile -Command Get-Date 2>/dev/null || /mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe -NoProfile -Command Get-Date

Fix#

sudo hwclock -s || sudo systemctl restart systemd-timesyncd

Verify#

date in WSL matches Windows, and sudo apt update runs without “not valid yet” errors.

GPU or CUDA not found#

nvidia-smi or CUDA does not see the GPU inside WSL. WSL uses the Windows driver; a Linux GPU driver breaks it.

Symptoms#

• nvidia-smi: command not found, or it reports no devices.
• torch.cuda.is_available() returns False.

Diagnose#

ls /usr/lib/wsl/lib/ | grep -i -E 'cuda|nvidia'
/usr/lib/wsl/lib/nvidia-smi
dpkg -l | grep -i -E 'nvidia-driver|nvidia-dkms'     # should print nothing

Fix#

Verify#

nvidia-smi (or /usr/lib/wsl/lib/nvidia-smi) lists your GPU, and your framework reports CUDA as available.

code, explorer.exe or powershell.exe not found#

Windows programs stopped working from the WSL shell. Usually appendWindowsPath=false removed them from PATH, which is fixable without undoing it.

Symptoms#

• code: command not found or powershell.exe: command not found
• explorer.exe . stopped opening Explorer

Diagnose#

grep -A3 '^\[interop\]' /etc/wsl.conf
ls /mnt/c/Windows/System32/cmd.exe
cat /proc/sys/fs/binfmt_misc/WSLInterop 2>/dev/null | head -n 1   # "enabled" = Windows .exe files can run

Fix#

Verify#

code --version and explorer.exe . work from the WSL shell.

node or npm is the Windows one#

which node points into /mnt/c, so a Windows Node.js runs against Linux files, with slow installs and broken native modules.

Symptoms#

• which node prints /mnt/c/Program Files/nodejs/node.
• Installs are very slow, or native modules fail with invalid ELF header.
• npm scripts fail with '\r': command not found or Windows-style paths.

Diagnose#

which -a node npm npx pnpm
echo "$PATH" | tr ':' '\n' | grep -n -E 'mise|nvm|/mnt/c'

Fix#

Verify#

which node prints a path under ~/.local/share/mise (or ~/.nvm), and node -p process.platform prints linux.

sudo -E fails or is ignored#

Newer Ubuntu releases ship sudo-rs, which does not support every option of classic sudo. Pass the variables explicitly instead.

Symptoms#

• sudo -E some-command reports an unknown or unsupported option.
• Variables you exported are missing inside the command run with sudo.

Diagnose#

sudo --version | head -n 1      # "sudo-rs …" or "Sudo version 1.9…"

Fix#

sudo env HTTPS_PROXY="$HTTPS_PROXY" FOO=bar some-command

Verify#

sudo env FOO=bar sh -c 'echo $FOO' prints bar.

Every file shows as changed#

git status lists files you never touched, or scripts fail with $'\r' errors. Something wrote Windows line endings (CRLF) or changed file modes.

Symptoms#

• git status shows many modified files with no visible change.
• git diff shows ^M at line ends, or old mode 100644 / new mode 100755.
• Shell scripts fail with $'\r': command not found or /bin/bash^M: bad interpreter.

Diagnose#

git diff --stat | tail -n 3
git diff | grep -c $'\r'             # > 0 = CRLF in the changes
git config --show-origin --get-all core.autocrlf
git config --get core.filemode
pwd                                  # /mnt/c/… = repo on the Windows drive

Fix#

git config --global core.autocrlf input
printf '* text=auto eol=lf\n' >> .gitattributes
git add --renormalize .

Verify#

git status is clean, and scripts run without \r errors.