Claude Code on WSL2 Keeps Disconnecting — Causes and Fixes

If Claude Code suddenly freezes on WSL2, the most likely culprit is VMMem memory bloat. Setting a memory cap and enabling autoMemoryReclaim in .wslconfig fixes it in most cases.

Here's what typically happens — you're mid-session when everything freezes. Task Manager shows VMMem eating a massive chunk of RAM. Windows runs out of memory and kills the WSL2 VM. All your in-progress context — gone. This scenario comes up constantly in GitHub Issues and developer forums.

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 50% of your physical memory (Microsoft docs). On a 16GB machine, that's 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

[experimental]
autoMemoryReclaim=dropcache
sparseVhd=true

autoMemoryReclaim=dropcache tells WSL2 to immediately release cached memory instead of hoarding it. Available since WSL 1.3.10. You can also use gradual (releases slowly when idle), but dropcache is more aggressive and better suited for file-heavy workloads like Claude Code. sparseVhd=true automatically shrinks the virtual disk when space is freed.

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

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

After saving, restart WSL to apply the changes. Note the 8-second rule — WSL needs a few seconds to fully stop before picking up new settings.

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.

If sleep-related network drops happen frequently, try networkingMode=mirrored in your .wslconfig. This mirrors WSL2's network stack with Windows and can improve network recovery after resume (requires Windows 11 22H2+).

[wsl2]
networkingMode=mirrored

Be aware that mirrored mode has known issues — Docker Desktop compatibility and VPN setups may break. Try it and revert if you hit problems.

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. Frequent disconnects on the Canary channel are well-documented in GitHub Issues — switching back to stable is the safest bet.

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

As of March 2026, the latest WSL2 kernel is 6.6.114.1. If your kernel version is older, updating may fix known stability bugs. Check the WSL kernel release notes for details on what's changed.

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.

Frequently Asked Questions

Why does VMMem use so much memory?

WSL2 runs on a Hyper-V virtual machine, and VMMem represents its memory usage on the Windows side. The Linux kernel keeps file caches in RAM by design. With Claude Code's constant file reads and writes, this cache grows fast and isn't released back to Windows without autoMemoryReclaim configured.

How do I prevent WSL2 from disconnecting?

Set a memory cap (e.g. memory=8GB) and swap size in .wslconfig, and add autoMemoryReclaim=dropcache under [experimental]. If you're on a Windows Insider build, consider switching to the stable channel.

Does a WSL2 disconnect erase my Claude Code work?

Yes, your session context is lost. Mitigate this by designing your CLAUDE.md to record work state and committing to git frequently.

What's the difference between autoMemoryReclaim "gradual" and "dropcache"?

gradual releases cached memory slowly when the VM is idle. dropcache releases it immediately. For file-heavy workloads like Claude Code, dropcache is more effective. Note that gradual has known compatibility issues with zswap — switch to dropcache if you experience problems.

Should I use networkingMode=mirrored?

Try it if you frequently lose network connectivity after sleep/resume. However, it can cause issues with Docker Desktop and VPN setups. Start with the default NAT mode and switch only if network problems persist.

What's the difference between WSL1 and WSL2?

WSL1 translates Linux syscalls on the Windows kernel. WSL2 runs a real Linux kernel in a lightweight VM. For Claude Code with its heavy file I/O and Node.js builds, WSL2 offers better compatibility — but its VM architecture means you need .wslconfig to manage memory.

How do I keep Claude Code stable during long WSL2 sessions?

Combine token cost optimization with long session management. Monitor VMMem in Task Manager — if it exceeds 40% of your physical RAM, restart WSL with wsl --shutdown before it crashes on its own.

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.

For non-WSL issues, check the Claude Code Troubleshooting Complete Guide. If you're setting up Docker on WSL2, see Claude Code × Docker Dev Environment Setup.