Estaba en medio de escribir código con Claude Code cuando todo se congeló. No aceptaba entrada. Unos segundos después: "Connection to WSL was lost." Todo mi contexto en progreso se perdió.
Al principio, asumí que era un problema de Claude Code. Quizás alcancé el límite de tokens, o la API se cayó. Pero después de investigar, el culpable no era Claude Code en absoluto: era WSL2 en sí.
Este artículo explica por qué WSL2 se desconecta aleatoriamente mientras usas Claude Code y te guía a través de soluciones concretas. Guárdalo en favoritos para la próxima vez que suceda.
¿Cómo Sabes Si la Desconexión Es un Problema de WSL2?
Primero, necesitas confirmar que WSL2 es realmente la causa. Estos patrones apuntan a un problema a nivel de WSL2:
- La respuesta de Claude Code se detiene repentinamente y toda la terminal se congela
- La terminal muestra "connection lost" o "process terminated"
- La conexión de VS Code Remote WSL se cae al mismo tiempo
- Todos los demás procesos dentro de WSL (servidores de desarrollo, herramientas de build) también mueren
Si solo Claude Code se detiene pero WSL sigue vivo, consulta la guía de solución de problemas de Claude Code primero.
¿Por Qué la Inflación de Memoria de VMMem Causa que WSL2 Se Caiga?
WSL2 se ejecuta como una VM ligera (Hyper-V) en Windows. Esta VM aparece como el proceso VMMem en el lado de Windows.
El problema: WSL2 reclama memoria agresivamente pero raramente la devuelve. Esto es por diseño; el kernel de Linux mantiene cachés de archivos en memoria. Cuando estás ejecutando Claude Code, que lee y escribe archivos constantemente, esto se acumula rápido.
Antes de darte cuenta, VMMem está consumiendo 10GB, 15GB de RAM. Windows se queda sin memoria y mata la VM de WSL2 a la fuerza.
Cómo Verificar
Abre el Administrador de Tareas de Windows y mira el uso de memoria de VMMem. Si supera el 50% de tu RAM física, es una señal de alarma.
# También puedes verificar desde PowerShell
Get-Process vmmem -ErrorAction SilentlyContinue | Select-Object WorkingSet64
¿Por Qué la Ausencia de .wslconfig Causa Desconexiones de WSL2?
Por defecto, WSL2 puede usar hasta el 80% de tu memoria física. En una máquina de 16GB, eso son aproximadamente 12.8GB disponibles para WSL2.
Ejecuta Claude Code junto con VS Code, un navegador y Docker, y agotarás la memoria rápidamente.
Solución: Establecer Límites de Memoria con .wslconfig
Crea o edita %UserProfile%\.wslconfig en el lado de Windows.
[wsl2]
memory=8GB
swap=4GB
localhostForwarding=true
El archivo va en C:\Users\<TuNombreDeUsuario>\.wslconfig.
# Crearlo desde PowerShell
notepad "$env:USERPROFILE\.wslconfig"
Después de guardar, reinicia WSL para aplicar los cambios.
wsl --shutdown
La nueva configuración toma efecto la próxima vez que abras WSL.
| RAM Física | Configuración Recomendada | Razonamiento |
|---|---|---|
| 16GB | memory=6GB | Dejar 10GB para Windows |
| 32GB | memory=12GB | Margen cómodo |
| 64GB | memory=24GB | Espacio de sobra |
Una buena regla general es asignar 1/3 a 1/2 de tu RAM física a WSL2. Claude Code en sí no consume mucha memoria, pero combínalo con builds de Node.js y compilación de TypeScript y el uso se dispara rápido. Mejor ser conservador.
¿Por Qué WSL2 Se Rompe Después de Suspensión o Hibernación?
Cuando tu PC despierta de suspensión o hibernación, la VM de WSL2 a veces no se reanuda limpiamente. El stack de red es especialmente frágil.
Después de reanudar, Claude Code puede fallar al alcanzar la API, o la red de WSL puede estar completamente rota.
Solución
Si las cosas están inestables después de reanudar, reinicia WSL.
wsl --shutdown
Luego vuelve a abrir WSL. Tu sesión de Claude Code se perderá, pero si tienes un CLAUDE.md bien mantenido y commits recientes en git, la recuperación es rápida.
¿Pueden las Builds de Windows Insider Causar Desconexiones de WSL2?
Si estás en el Programa Windows Insider (canal Dev / Canary), la estabilidad de WSL2 puede sufrir.
Por ejemplo, la build de Windows 10.0.26200 es una preview del canal Canary con cambios frecuentes de Hyper-V. Como WSL2 se ejecuta sobre Hyper-V, se ve directamente afectado.
Cómo Verificar
# Verifica tu número de build de Windows
winver
Si tu número de build es superior al de la versión estable (serie 26100), estás en una build Insider.
Solución
- Reporta desconexiones de WSL a través del Feedback Hub: Microsoft prioriza el feedback de Insiders
- Si la estabilidad es tu prioridad, cambia al canal Release Preview o abandona el Programa Insider por completo
- Mantén WSL actualizado:
wsl --update
¿Puede un Kernel WSL Desactualizado Causar Desconexiones?
Una versión antigua del kernel de WSL2 puede tener bugs conocidos que causan desconexiones.
wsl --version
Esto muestra tu versión de WSL y la versión del kernel. Mantenlos actualizados.
wsl --update
WSL 2.x es significativamente más estable que 1.x. Si todavía estás en 1.x, actualizar vale mucho la pena.
¿Cómo Proteges Tu Trabajo Cuando WSL2 Se Cae?
No puedes prevenir completamente las desconexiones de WSL2. Así que también necesitas una estrategia para minimizar el daño.
Mantén Tu CLAUDE.md Actualizado
Claude Code lee CLAUDE.md al inicio de cada sesión. Escribe ahí el contexto de tu proyecto y la tarea actual para que las nuevas sesiones puedan continuar donde te quedaste.
# CLAUDE.md
## Project overview
- Next.js 16 + App Router
- TypeScript strict mode
## Current work
- Implementing feature X. Editing `src/components/Feature.tsx`
Haz Commits en Git Frecuentemente
Haz commits temprano, haz commits seguido. Incluso commits de trabajo en progreso previenen la pérdida de código en una desconexión. Puedes decirle a Claude Code que "haga commit en buenos puntos de parada" como parte de tu flujo de trabajo.
Usa tmux / screen (Ayuda Limitada)
Los multiplexores de terminal sobreviven a desconexiones SSH, pero si la VM de WSL2 en sí se cae, tmux cae con ella. Ayudan con caídas transitorias de red pero no con fallos a nivel de VM.
Conclusión
Las desconexiones de WSL2 mientras usas Claude Code se reducen a cinco causas principales:
- Inflación de memoria de VMMem — Establece límites de memoria en
.wslconfig - Sin .wslconfig configurado — Crea uno inmediatamente
- Corrupción de VM por suspensión/reanudación — Reinicia con
wsl --shutdown - Inestabilidad de Windows Insider Build — Considera el canal estable
- Kernel WSL desactualizado — Ejecuta
wsl --update
Y como las desconexiones no se pueden eliminar por completo, mantén tu CLAUDE.md y haz commits en git frecuentemente para minimizar el radio de impacto. Claude Code y WSL2 son una combinación poderosa, pero esta pequeña preparación marca toda la diferencia.