microsoft / microsoft/WSL

WSL integration with Docker Desktop intermittently fails with "HCS_E_CONNECTION_TIMEOUT" after forced Windows shutdown

Open
#13,578 1 comment 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.