WSL integration with Docker Desktop intermittently fails with "HCS_E_CONNECTION_TIMEOUT" after forced Windows shutdown
- Dominant language
- C++
- Stars
- 33.7k
- Forks
- 1.8k
- Avg merge
- 3d 17h
- Merged PRs (30d)
- 116
Description
I installed wordpress-develop ( https://github.com/WordPress/wordpress-develop.) and it started up successfully, but while I was developing a WordPress project on that container, Windows forced a shutdown.
As a result, I got a message like "WSL integration with distro 'Ubuntu-24.04' unexpectedly stopped. Do you want to restart it?" (on Docker Desktop)
Then I followed that message, and retried connecting to WSL in VS Code. Once I succeeded to log in the WSL shell, but after that, it fails intermittently. ( When I successfully logged in, I could connect to WSL normally for a while. But after a few days, the error code "HCS_E_CONNECTION_TIMEOUT" appears and the connection fails. )
Even if I try to connect directly to WSL in Powershell, the same "HCS_E_CONNECTION_TIMEOUT" appears.
### Environment
#### Windows Version
Windows 11 Home 10.0.26100.6584 (Build 26100.6584)
#### WSL Version
2.5.10.0
#### Are you using WSL 1 or WSL 2?
- [ ] WSL 1
- [x] WSL 2
#### Kernel Version
6.6.87.2-1
#### Distro Version
Ubuntu 24.04.2 LTS
#### Other Software
docker desktop windows 4.37.1(178610)
#### Node.js, npm
I forgot to take output while WSL was successfully running, so I'm not able to get their details.
I've already logged out of WSL and can't reconnect, so I don't know the exact version or some info like that.
### Reproduction Steps
1. Inside WSL, I installed the container using Node.js and npm.
Note: The specific project ( wordpress-develop ) is not essential to reproducing the issue, but it reflects the kind of workload I was running.
1. Windows triggered a forced shutdown ( due to crash by a watchdog_violation ) while container is running.
1. Upon reboot, Docker Desktop shows:
"WSL integration with distro 'Ubuntu-24.04' unexpectedly stopped. Do you want to restart it?"
1. Retry WSL connection via VS Code or PowerShell.
1. Once login attempting succeeded, but fails with "HCS_E_CONNECTION_TIMEOUT" again after a few days.
### Powershell Logs
**When succeeds:**
[WslLogs-2025-09-29_11-05-52.zip](https://github.com/user-attachments/files/22587951/WslLogs-2025-09-29_11-05-52.zip)
**When fails**
[WslLogs-2025-10-06_14-41-45.zip](https://github.com/user-attachments/files/22715701/WslLogs-2025-10-06_14-41-45.zip)
### What I Tried ( when I got the Error code at the first time )
**1. Ensure WSL integration is enabled**
Settings > Resources > WSL integration
Click "Restart the WSL Integration" Button on the message window above.
**2. Connect to WSL (vscode)**
Ctrl Shift P > Connect to WSL
**3. Check the syslog (WSL)**
```
PowerShell 7.5.3
PS C:\Windows\System32> wsl -d Ubuntu-24.04
xxx@Ataraxia:/mnt/c/Windows/System32$ sudo journalctl -f
[sudo] password for xxx:
```
I tried using `journalctl` as shown above, but nothing came up.
note :
System logging is disabled by default in WSL.
So I added the following to `/etc/wsl.conf` on Ubuntu-24.04:
``` conf:/etc/wsl.conf
[boot]
systemd=true
```
Exit WSL:
```
xxx@Ataraxia:/mnt/c/Windows/System32$ exit
```
Then, completely restart WSL using PowerShell:
```
PS C:\Windows\System32> wsl --shutdown
PS C:\Windows\System32> wsl -d Ubuntu-24.04
```
View the system log again:
```
xxx@Ataraxia:/mnt/c/Windows/System32$ sudo journalctl -f
WARNING Daemon: could not connect to Windows Agent: could not get address: could not read agent port file "/mnt/c/Users/cinem/.ubuntupro/.address": open /mnt/c/Users/cinem/.ubuntupro/.address: no such file or directory
Sep 28 11:47:16 Ataraxia wsl-pro-service[229]: INFO Reconnecting to Windows host in 60 seconds
```
Searching for the error message reveals an issue on GitHub, but it was closed without a solution. ↓
https://github.com/microsoft/WSL/issues/12433
**Close VS Code**
Close normally
**Start WSL**
After attempting to start WSL, I failed with the error code `Wsl/Service/HCS_E_CONNECTION_TIMEOUT`.
```
PS C:\Users\cinem> wsl -d Ubuntu-24.04
The operation timed out because no response was received from the virtual machine or container.
Error Code: Wsl/Service/HCS_E_CONNECTION_TIMEOUT
```
### Additional notes
In the issue (https://github.com/microsoft/WSL/issues/12433) I mentioned above,
an ubuntu-pro-client related problem was mentioned in another issue (https://github.com/microsoft/WSL/issues/12992) which was opened by 12433's author after former 12433 was closed by bot.
Quoting a comment from issue 12992:
>This appears to be an issue with the wsl-pro-service malfunctioning, I would recommend filing a bug there for that team to address.
>
>In the interim you can uninstall the Ubuntu Pro client with `sudo apt remove ubuntu-pro-client`.
But removing "ubuntu-pro-client" apt package is not available option for me, because I still cannot log in my WSL shell due to "HCS_E_CONNECTION_TIMEOUT" I mentioned.
Contributor guide
Research direction
Start with the reported `wsl -d Ubuntu-24.04` failure and the attached successful and failing WSL logs. Review the `/etc/wsl.conf` systemd setting and compare behavior after `wsl --shutdown`, including the `wsl-pro-service` messages. Done means identifying a reproducible cause or actionable fix for `HCS_E_CONNECTION_TIMEOUT` after the forced shutdown.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- docker, linux, powershell, ubuntu
- Domain
- devops, operating-systems
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100