Si usas Docker Desktop en Windows, es posible que en algún momento te hayas encontrado con el temido error “WSL inesperado”. Este problema impide que Docker funcione correctamente, lo que puede ser frustrante si estás en medio de un proyecto.
Pero no te preocupes. En esta guía te explicaré qué causa este error y cómo solucionarlo paso a paso. Además, compartiré mi propia experiencia enfrentándolo y cómo logré arreglarlo de forma definitiva.
🔥 IMPORTANTE: Este tutorial también sirve como base para un video de YouTube. Si prefieres ver el proceso en acción, te recomiendo seguir la versión en video cuando esté disponible.
🔍 ¿Qué causa el error “WSL inesperado” en Docker Desktop?
Antes de solucionar el problema, es importante entender qué lo causa. El mensaje de error generalmente se ve algo así:
Docker Desktop unexpected WSL error
«An unexpected error was encountered while executing a WSL command.»
Las principales causas de este error son:
✅ Problemas de permisos en WSL → Docker no puede acceder correctamente al subsistema Linux.
✅ Suspensión o reinicio del equipo → Si tu computadora se suspendió con Docker abierto, puede generar conflictos al reanudar.
✅ Actualizaciones de Windows o Docker → Algunas actualizaciones pueden cambiar configuraciones en WSL.
✅ WSL o Docker desactualizados → Si usas versiones antiguas, pueden no ser compatibles entre sí.
✅ Problemas en la configuración de red → Fallos en la caché DNS o en la configuración Winsock pueden afectar a Docker.
✅ Hyper-V o Subsistema de Windows para Linux desactivados → Algunas configuraciones esenciales pueden estar deshabilitadas.
Ahora que sabes por qué ocurre este error, vamos a solucionarlo paso a paso.
🛠 Métodos para solucionar el error
Voy a explicarte las cinco soluciones más efectivas, ordenadas de menor a mayor complejidad. Te recomiendo probarlas en este orden hasta que el problema se resuelva.
🔹 Método 1: Reiniciar el servicio WSL
El primer paso es forzar el reinicio de WSL, ya que muchas veces el error ocurre porque el servicio está en un estado inestable.
✍️ Pasos:
1️⃣ Abre PowerShell como administrador (clic derecho en el botón de inicio > «Windows PowerShell (Admin)»).
2️⃣ Escribe el siguiente comando y presiona Enter:
wsl -shutdown
3️⃣ Cierra PowerShell y abre Docker Desktop nuevamente.
Esto reiniciará el subsistema Linux. Si el error persiste, pasa al siguiente método.
🔹 Método 2: Actualizar WSL
Si el problema está relacionado con una versión desactualizada de WSL, actualizarlo puede ser la solución.
✍️ Pasos:
1️⃣ Abre PowerShell como administrador.
2️⃣ Escribe el siguiente comando y presiona Enter:
wsl -update
3️⃣ Espera a que termine la actualización. Luego, reinicia tu computadora y prueba Docker nuevamente.
Si el problema sigue, pasemos al siguiente método.
🔹 Método 3: Restablecer la configuración de red
Si el error está relacionado con la conexión entre Docker y WSL, este método lo solucionará.
✍️ Pasos:
1️⃣ Abre Símbolo del sistema (CMD) como administrador.
2️⃣ Ejecuta estos dos comandos uno por uno, presionando Enter después de cada uno:
ipconfig /flushdns
netsh winsock reset
3️⃣ Reinicia tu computadora y abre Docker.
🔹 Método 4: Revisar y activar características de Windows
Algunas características esenciales para Docker y WSL pueden estar desactivadas.
✍️ Pasos:
1️⃣ Escribe en la barra de búsqueda de Windows: «Activar o desactivar características de Windows» y ábrelo.
2️⃣ Asegúrate de que estas opciones estén activadas:
✅ Subsistema de Windows para Linux
✅ Plataforma de máquina virtual
✅ Hyper-V
3️⃣ Si alguna estaba desactivada, márcala, haz clic en Aceptar y reinicia tu PC.
Si tras esto Docker sigue sin funcionar, prueba el último método.
🔹 Método 5: Desinstalar y reinstalar Docker y WSL
Si nada de lo anterior funcionó, es hora de hacer una reinstalación completa.
✍️ Pasos:
1️⃣ Desinstala Docker desde «Agregar o quitar programas».
2️⃣ Desinstala WSL ejecutando este comando en PowerShell:
wsl -unregister <nombre_de_la_distro>
(Sustituye <nombre_de_la_distro> por el nombre de tu distribución de Linux. Puedes verlo con wsl -l.)
3️⃣ Reinicia tu computadora.
4️⃣ Descarga e instala la última versión de Docker Desktop y WSL desde sus sitios oficiales.
5️⃣ Configura Docker nuevamente y prueba si el error desapareció.
📝 Mi experiencia personal resolviendo este error
Cuando me encontré con este problema, probé varias soluciones sin éxito. Inicialmente, pensé que reiniciar WSL sería suficiente, pero el error seguía apareciendo.
Lo que realmente funcionó para mí fue actualizar WSL con wsl --update, seguido de un flush de DNS y un reset de Winsock. Esto solucionó el problema sin necesidad de reinstalar Docker.
Otro consejo que descubrí es que evitar suspender la computadora con Docker abierto reduce la probabilidad de que este error vuelva a ocurrir.
Si estás enfrentando este problema, te recomiendo seguir los métodos en orden. En la mayoría de los casos, actualizar WSL y restablecer la red es suficiente.
💡 Consejos adicionales para evitar futuros errores
✅ Mantén WSL y Docker actualizados: Las versiones antiguas suelen ser incompatibles con actualizaciones de Windows.
✅ Evita suspender tu PC con Docker abierto: Esto suele generar conflictos al reanudar.
✅ Verifica los permisos de WSL: Asegúrate de que tu usuario tenga acceso completo a la configuración de Docker.
✅ Realiza copias de seguridad de tus contenedores: Si el error persiste y debes reinstalar, tener un backup te ahorrará tiempo.
🎯 Conclusión
El error “WSL inesperado” en Docker Desktop puede ser molesto, pero en la mayoría de los casos tiene solución rápida.
📌 Resumen de soluciones:
✔ Reinicia WSL con wsl -shutdown.
✔ Actualiza WSL con wsl -update.
✔ Restablece la red con ipconfig /flushdns y netsh winsock reset.
✔ Verifica que Hyper-V y WSL estén activados.
✔ Reinstala Docker y WSL si nada funciona.
Si este tutorial te ayudó, compártelo y deja tu comentario.