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

[David-JA]

Windows Version

10.0.26200.8457

WSL Version

2.6.3

Are you using WSL 1 or WSL 2?

• 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:

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

3. Run:

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:

\SOFTWARE\Classes\Directory\shell\WSL

6. After the failed update, run:

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:

wsl
wsl -d <DistributionName>
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:

wsl --update

produces:

正在检查更新。
正在更新适用于 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:

wsl --status

produces:

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:

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:

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.

[github-actions]

Logs are required for review from WSL team

If this a feature request, please reply with '/feature'. If this is a question, reply with '/question'.
Otherwise, please attach logs by following the instructions below, your issue will not be reviewed unless they are added. These logs will help us understand what is going on in your machine.

How to collect WSL logs

Download and execute collect-wsl-logs.ps1 in an administrative powershell prompt:

Invoke-WebRequest -UseBasicParsing "https://raw.githubusercontent.com/microsoft/WSL/master/diagnostics/collect-wsl-logs.ps1" -OutFile collect-wsl-logs.ps1
Set-ExecutionPolicy Bypass -Scope Process -Force
.\collect-wsl-logs.ps1

The script will output the path of the log file once done.

If this is a networking issue, please use .\collect-wsl-logs.ps1 -LogProfile networking instead, following the instructions in Collect WSL logs for networking issues

Once completed please upload the output files to this GitHub issue.

See Collect WSL logs (recommended method).

If you choose to email these logs instead of attaching them to the bug, please send them to wsl-gh-logs@microsoft.com with the GitHub issue number in the subject, and include a link to your GitHub issue comment in the message body, and reply with '/emailed-logs'.

[David-JA]

/question

Additional clarification:

I understand that the initial registry write failure may be caused by a third-party context menu manager or registry permission hardening. I am not expecting WSL to bypass intentionally restricted registry permissions.

The main bug I want to report is the failure handling behavior:

• Before running wsl --update, WSL 2.6.3 was installed and working.
• The update to 2.7.3 failed when writing Explorer context menu registry entries.
• After the failed update, the previous WSL 2.6.3 installation was no longer usable.
• wsl --status then reported Wsl/CallMsi/Install/REGDB_E_CLASSNOTREG.

So even if the registry write failure itself is expected under restricted permissions, the update process should either roll back cleanly or leave the existing WSL installation intact. A failed update should not leave WSL in a partially installed or corrupted state.

[github-actions]

Diagnostic information

Found '/question', adding tag 'question'

[chemwolf6922]

Hi @David-JA , Thanks for reporting this issue.
This PR #40524 is adding the rollback on update failures. But it's likely not a complete solution as there are custom actions in the installer that does not have a paring rollback action.

Windows is working on adding user-controlled context menu management Windows 11 Context Menus Reworked: Faster, Simpler, and Finally Configurable. So hopefully the third-party tool emplaced restriction won't be needed in the future.

For now, to temporarily solve your problem, please consider disable the custom protection, install wsl, and enable the protection again.