Claude Code on WSL2 Keeps Disconnecting — Causes and Fixes

I was in the middle of writing code with Claude Code when everything froze. No input accepted. A few seconds later: "Connection to WSL was lost." All my in-progress context — gone.

At first, I assumed it was a Claude Code issue. Maybe I hit the token limit, or the API went down. But after digging into it, the culprit wasn't Claude Code at all — it was WSL2 itself.

This article explains why WSL2 randomly disconnects while you're using Claude Code and walks through concrete fixes. Bookmark this for the next time it happens.

How Do You Tell If the Disconnect Is a WSL2 Problem?

First, you need to confirm that WSL2 is actually the cause. These patterns point to a WSL2-level issue:

• Claude Code's response suddenly stops and the entire terminal freezes
• Terminal shows "connection lost" or "process terminated"
• VS Code Remote WSL connection drops at the same time
• All other processes inside WSL (dev servers, build tools) also die

If only Claude Code stops but WSL itself stays alive, check the Claude Code troubleshooting guide first.

Why Does VMMem Memory Bloat Cause WSL2 to Crash?

WSL2 runs as a lightweight VM (Hyper-V) on Windows. This VM appears as the VMMem process on the Windows side.

The problem: WSL2 aggressively claims memory but rarely gives it back. This is by design — the Linux kernel keeps file caches in memory. When you're running Claude Code, which reads and writes files constantly, this adds up fast.

Before you know it, VMMem is eating 10GB, 15GB of RAM. Windows runs out of memory and force-kills the WSL2 VM.

How to Check

Open Windows Task Manager and look at VMMem's memory usage. If it's over 50% of your physical RAM, that's a red flag.

# You can also check from PowerShell
Get-Process vmmem -ErrorAction SilentlyContinue | Select-Object WorkingSet64

Why Does a Missing .wslconfig Lead to WSL2 Disconnects?

By default, WSL2 can use up to 80% of your physical memory. On a 16GB machine, that's roughly 12.8GB available to WSL2.

Run Claude Code alongside VS Code, a browser, and Docker, and you'll exhaust memory quickly.

Fix: Set Memory Limits with .wslconfig

Create or edit %UserProfile%\.wslconfig on the Windows side.

[wsl2]
memory=8GB
swap=4GB
localhostForwarding=true

The file goes at C:\Users\<YourUsername>\.wslconfig.

# Create it from PowerShell
notepad "$env:USERPROFILE\.wslconfig"

After saving, restart WSL to apply the changes.

wsl --shutdown

The new settings take effect the next time you open WSL.

A good rule of thumb is allocating 1/3 to 1/2 of your physical RAM to WSL2. Claude Code itself doesn't consume much memory, but combine it with Node.js builds and TypeScript compilation and usage spikes fast. Err on the conservative side.

Why Does WSL2 Break After Sleep or Hibernate?

When your PC wakes from sleep or hibernation, the WSL2 VM sometimes fails to resume cleanly. The network stack is especially fragile.

After resume, Claude Code may fail to reach the API, or WSL's networking may be completely broken.

Fix

If things are unstable after resume, restart WSL.

wsl --shutdown

Then reopen WSL. Your Claude Code session will be lost, but if you have a well-maintained CLAUDE.md and recent git commits, recovery is fast.

Can Windows Insider Builds Cause WSL2 Disconnections?

If you're on the Windows Insider Program (Dev / Canary channel), WSL2 stability can suffer.

For example, Windows build 10.0.26200 is a Canary channel preview with frequent Hyper-V changes. Since WSL2 runs on Hyper-V, it's directly affected.

How to Check

# Check your Windows build number
winver

If your build number is higher than the stable release (26100 series), you're on an Insider build.

Fix

• Report WSL disconnects through Feedback Hub — Microsoft prioritizes Insider feedback
• If stability is your priority, switch to the Release Preview channel or leave the Insider Program entirely
• Keep WSL itself up to date: wsl --update

Can an Outdated WSL Kernel Cause Disconnects?

An old WSL2 kernel version may have known bugs that cause disconnects.

wsl --version

This shows your WSL version and kernel version. Keep them updated.

wsl --update

WSL 2.x is significantly more stable than 1.x. If you're still on 1.x, updating is well worth it.

How Do You Protect Your Work When WSL2 Drops?

You can't completely prevent WSL2 disconnects. So you also need a strategy to minimize the damage.

Keep Your CLAUDE.md Up to Date

Claude Code reads CLAUDE.md at the start of every session. Write your project context and current task there so new sessions can pick up where you left off.

# CLAUDE.md

## Project overview
- Next.js 16 + App Router
- TypeScript strict mode

## Current work
- Implementing feature X. Editing `src/components/Feature.tsx`

Commit to Git Frequently

Commit early, commit often. Even work-in-progress commits prevent code loss on disconnect. You can tell Claude Code to "commit at good stopping points" as part of your workflow.

Use tmux / screen (Limited Help)

Terminal multiplexers survive SSH disconnects, but if the WSL2 VM itself crashes, tmux goes down with it. They help with transient network drops but not VM-level failures.

Wrapping Up

WSL2 disconnects while using Claude Code come down to five main causes:

1. VMMem memory bloat — Set memory limits in .wslconfig
2. No .wslconfig configured — Create one immediately
3. Sleep/resume VM corruption — Restart with wsl --shutdown
4. Windows Insider Build instability — Consider the stable channel
5. Outdated WSL kernel — Run wsl --update

And since disconnects can't be fully eliminated, maintain your CLAUDE.md and commit to git frequently to minimize the blast radius. Claude Code and WSL2 are a powerful combination, but this small bit of preparation makes all the difference.