Skip to content

Claude Code Complete Guide

Claude Code Keeps Crashing on WSL2 — OOM Kill Causes and Fixes

For / Key Points

For: Developers running Claude Code on WSL2 who experience sudden process termination and cannot resume sessions.

Key Points:

  • Claude Code has a known memory leak that triggers OOM Kill within minutes to hours under WSL2's default memory limits
  • Force-killed sessions corrupt the session index, making --resume unusable
  • Adjusting .wslconfig memory/swap settings and adopting session management practices significantly reduces occurrence

What Happens

You're working in Claude Code, and suddenly the process vanishes. No error message in the terminal. You try claude --resume to pick up where you left off, but the session is gone.

This is the Linux kernel's OOM Killer (Out of Memory Killer) force-terminating the Claude Code process. When physical memory and swap are exhausted, the kernel selects the process with the highest memory consumption and sends SIGKILL (signal 9) for immediate termination1.

Since this isn't a graceful shutdown, Claude Code dies without writing session files. The result: session resume is broken.

Why Claude Code Exhausts Memory

The root cause is a memory leak in Claude Code itself. Numerous issues have been filed on GitHub.

ArrayBuffers accumulate indefinitely on the Node.js V8 heap. One issue measured memory growing at approximately 92 GB per hour2. Another report documented a process consuming over 120 GB of RAM before being OOM-killed3.

Tracing the actual sequence of events:

Claude Code starts → repeated tool executions within session → conversation context + tool results accumulate in memory → V8 heap balloons → physical memory + swap exhausted → kernel OOM Killer fires → SIGKILL instant death → sessions-index.json not updated → --resume fails

WSL2 makes this problem particularly acute for two reasons.

First, WSL2's default memory cap is low. WSL2 defaults to 50% of the host PC's physical memory4. On a 16 GB machine, that's about 8 GB, with 4 GB of swap (25% of RAM). Add resident services (Elastic Agent, PostgreSQL, Zabbix, etc.) and you have only a few GB of headroom.

Second, the March 2026 Windows update KB5079473 made things worse. After this patch, Claude Code reportedly hits heap exhaustion at 4.6 GB consistently on WSL25. This affects Windows 11 25H2/24H2, impacting a large number of developers.

How to Confirm OOM Kill

Run the following in your WSL2 terminal:

# Search kernel logs for OOM Kill records
dmesg | grep -i "oom\|killed process" | tail -20

If you see a line like Out of memory: Killed process XXXXX (claude), OOM Kill is confirmed. The total-vm (virtual memory) and anon-rss (resident memory) values tell you how much memory was consumed at the time of the kill.

Check current memory status with:

# System-wide memory status
free -h

# Claude Code process memory usage
ps aux --sort=-%mem | grep -E "claude|RSS" | head -10

If swap usage exceeds 80%, OOM Kill could happen at any moment.

Fix 1: Increase WSL2 Resource Limits via .wslconfig

Increase the memory and swap allocated to WSL2. Edit %USERPROFILE%\.wslconfig on the Windows side.

Values depend on your environment

The following is an example for a PC with 16 GB physical RAM, not a universal setting. Appropriate values vary by host memory, Windows-side usage, and resident services in WSL2. Run free -h first to understand your current state, then adjust accordingly.

[wsl2]
memory=10GB
swap=8GB
ItemDefault (16 GB PC)ExampleEffect
WSL2 RAM8 GB10 GB+2 GB headroom for Claude Code + services
WSL2 Swap4 GB8 GB+4 GB buffer for memory spikes
Total12 GB18 GBOOM Kill threshold increased by 50%

Restart WSL to apply. Run from PowerShell:

wsl --shutdown

Caution

wsl --shutdown stops all WSL processes. Claude Code sessions will be terminated, so run this at a natural break point.

This setting involves trade-offs. On a 16 GB PC, allocating 10 GB to WSL2 leaves only 6 GB for Windows. Heavy browser and IDE usage will push Windows into swapping, degrading performance. PCs with 32 GB+ can afford generous allocations; 8 GB PCs cannot use these values at all. Increasing swap is lower risk (disk I/O slows down, but OOM Kill is prevented), so consider bumping swap first and observing.

Fix 2: Limit Claude Code Memory with cgroups

The fundamental fix requires Anthropic to patch the leak, but you can cap per-process memory so a runaway process doesn't take down everything else.

# For cgroup v2 (Ubuntu 22.04+ on WSL2)
sudo mkdir -p /sys/fs/cgroup/claude
echo "4G" | sudo tee /sys/fs/cgroup/claude/memory.max
echo $$ | sudo tee /sys/fs/cgroup/claude/cgroup.procs
claude  # Claude Code launched from this shell gets a 4 GB limit

With this approach, only the Claude Code process gets killed at 4 GB, leaving PostgreSQL, Elastic Agent, and other services unaffected.

Fix 3: Session Recovery

After OOM Kill, session data usually survives even when --resume can't find it6.

# Find session files modified within the last day
find ~/.claude/projects/ -name "*.jsonl" -mtime -1 -ls

# Locate sessions-index.json
find ~/.claude/ -name "sessions-index.json" -ls

If session JSONL files exist but are missing from the index, rebuilding the index restores them. See the Zenn article6 for detailed steps.

For future protection, back up important sessions regularly:

# Periodic session backup (recommended as a cron job)
mkdir -p ~/.claude/session-backups/$(date +%Y%m%d_%H%M%S)
cp -r ~/.claude/projects/ ~/.claude/session-backups/$(date +%Y%m%d_%H%M%S)/

Fix 4: Operational Workarounds

Combine technical fixes with session management changes to minimize damage.

Keep sessions short. Claude Code's memory leak worsens proportionally with session duration. After completing each task, git commit and end the session. Start the next task in a fresh session.

Note the session ID. Record the session ID displayed when Claude Code starts. claude --resume <ID> is more reliable than --continue (which auto-resumes the last session).

Check your Claude Code version. A critical memory leak was introduced in v2.1.27, causing memory to balloon to 7.5 GB within 20 seconds7. Verify your version and update to the latest.

npm update -g @anthropic-ai/claude-code
claude --version

Summary

The OOM Kill problem stems from Anthropic's memory leak bug — users cannot fully prevent it. However, proper WSL2 resource configuration and session management practices dramatically reduce both frequency and impact.

The highest-impact fix is editing .wslconfig (setting swap to 8 GB), which alone provides significant improvement. Long-term, wait for Anthropic's fix (ArrayBuffer accumulation resolution) while combining cgroup defenses with session backups for a practical operational strategy.

Memory leak issues continue to be reported and discussed on GitHub. Track Anthropic's progress through the issues linked below.

Post this article Copy link

  1. See the Linux kernel documentation on vm/oom_killer. When memory is fully exhausted, the process with the highest oom_score is terminated with SIGKILL. ↩

  2. GitHub Issue #32892 - Memory Leak: ArrayBuffer accumulation causing ~92 GB/hour growth (v2.1.71) ↩

  3. GitHub Issue #4953 - Claude Code Memory Leak - Process Grows to 120+ GB RAM and Gets OOM Killed ↩

  4. Microsoft documentation: Advanced settings configuration in WSL. When memory is unspecified in .wslconfig, it defaults to 50% of total Windows memory. swap defaults to 25% of RAM, rounded up to the nearest GB. ↩

  5. GitHub Issue #33415 - Windows 11 KB5079473 (March 2026) causes consistent heap exhaustion in Claude Code on WSL2 ↩

  6. Zenn - Missing Sessions in Claude Code --resume: How to Restore sessions-index.json. Recovery steps for when session JSONL files exist but are missing from sessions-index.json after OOM Kill. ↩↩

  7. GitHub Issue #22042 - Critical memory regression in 2.1.27 - OOM crash on simple input. In v2.1.27, memory ballooned from 467 MB to 7.5 GB within 20 seconds. v2.1.25 was stable. ↩