microsoft / microsoft/WSL

WSL update fails on Explorer context menu registry write and corrupts existing installation

Open
#40,707 4 comments 0 reactions 0 assignees View on GitHub
fixinbound install
Dominant language
C++
Stars
33.7k
Forks
1.8k
Avg merge
3d 17h
Merged PRs (30d)
116

Description

### Windows Version

10.0.26200.8457

### WSL Version

2.6.3

### Are you using WSL 1 or WSL 2?

- [x] WSL 2
- [ ] WSL 1

### Kernel Version

6.6.87.2-1

### Distro Version

ubuntu 24.04.4

### Other Software

I use a context menu management tool:

Context Menu Manager Plus
Version: 1.5.6
https://github.com/PLFJY/ContextMenuMgr

This tool has an option to prevent new Explorer context menu entries from being added by changing registry permissions. In my environment, this protection is intentional, because many applications add unnecessary Explorer right-click menu entries.

The relevant protected registry paths include Explorer context menu locations such as:

HKLM\SOFTWARE\Classes\Directory\shell
HKLM\SOFTWARE\Classes\Directory\Background\shell

### Repro Steps

1. Install WSL 2.6.3.
2. Enable registry-level protection against new Explorer context menu entries, or otherwise make the following registry paths not writable:

```text
HKLM\SOFTWARE\Classes\Directory\shell
HKLM\SOFTWARE\Classes\Directory\Background\shell
```

3. Run:

```powershell
wsl --update
```

4. WSL attempts to update to 2.7.3.
5. The update fails when the installer tries to write Explorer context menu registry entries, for example:

```text
\SOFTWARE\Classes\Directory\shell\WSL
```

6. After the failed update, run:

```powershell
wsl --status
```

7. WSL reports that the installation is damaged.

### Expected Behavior

If WSL update fails, the previously working WSL installation should remain usable.

Specifically:

1. The update process should roll back cleanly if installation fails.
2. A failure to write Explorer context menu registry entries should not corrupt the existing WSL installation.
3. Explorer context menu integration should be optional or non-fatal, because WSL core functionality does not depend on right-click menu entries.
4. If the installer cannot register Explorer context menu entries, it should log a warning and continue, or fail safely without damaging the existing installation.

WSL can normally be used through commands such as:

```powershell
wsl
wsl -d
wsl --status
wsl --list --verbose
```

Therefore, Explorer context menu registration should not be a required step for preserving or updating WSL core functionality.

### Actual Behavior

Running:

```powershell
wsl --update
```

produces:

```text
正在检查更新。
正在更新适用于 Linux 的 Windows 子系统: 2.7.3。
Could not write value to key \SOFTWARE\Classes\Directory\shell\WSL. Verify that you have sufficient access to that key, or contact your support personnel.
更新失败(退出代码: 1603)。
日志文件: C:\Users\fanmo\AppData\Local\Temp\wsl-install-logs.txt
错误代码: Wsl/UpdatePackage/ERROR_INSTALL_FAILURE
```

After this failed update, running:

```powershell
wsl --status
```

produces:

```text
wsl: WSL 安装似乎已损坏 (错误代码: Wsl/CallMsi/Install/REGDB_E_CLASSNOTREG)。
按任意键修复 WSL,或按 CTRL-C 取消。
此提示将在 60 秒后超时。
没有注册类
错误代码: Wsl/CallMsi/Install/REGDB_E_CLASSNOTREG
```

So the failed update does not simply fail safely. It leaves the previous working WSL 2.6.3 installation in a corrupted state.

### Diagnostic Logs

The update failure reports the following log file:

```text
C:\Users\fanmo\AppData\Local\Temp\wsl-install-logs.txt
```

I can provide the full log if needed.

Additional context:

The issue appears to happen during Explorer context menu registration. Manual MSI installation also showed similar errors, such as:

```text
Could not write value to key \SOFTWARE\Classes\Directory\Background\shell\WSL.
Verify that you have sufficient access to that key, or contact your support personnel.
```

The main bug is not only that the installer fails when it cannot write Explorer context menu entries. The more serious issue is that the failed update leaves the existing WSL installation corrupted instead of rolling back to the previously working version.

Explorer context menu integration is a convenience feature, not a core requirement. A failure in this non-essential registration step should not damage an existing WSL installation.

Contributor guide

Open the contributing guide

Research direction

Start by reproducing the update with the protected registry paths and inspect C:\Users\fanmo\AppData\Local\Temp\wsl-install-logs.txt, along with the reported MSI error. Trace the update and Explorer context-menu registration entry points to determine how failure affects the existing installation. Done means a blocked registry write fails safely, preserves the prior installation, and leaves wsl --status usable.

Written by the indexing model from the issue text.

Assessment

Tech stack
powershell
Domain
operating-systems, release
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.