Enable rollback on install failures during update by yeelam-gordon · Pull Request #40524 · microsoft/WSL

yeelam-gordon · 2026-05-13T14:54:01Z

Fix: all installed files lost on failed MSI upgrade

Problem

MajorUpgrade with no Schedule attribute (our previous state) uses the WiX default afterInstallValidate, which removes the old product outside the MSI transaction. If the new install fails afterward, all old files (~30 files, ~1.1GB including system.vhd) are gone with no rollback.

Even Worse: once files are lost, reinstalling does not recover them. Running msiexec /i again reports success but does nothing -- MSI thinks the product is already installed and skips all file operations. Recovery requires msiexec /fa (repair), REINSTALL=ALL, or full uninstall + reinstall -- none of which a typical user would know to try.

Fix

Add Schedule="afterInstallInitialize" -- this moves old product removal inside the transaction. On failure, MSI restores all files from .rbf backups automatically. The unrecoverable state is never reached.

Tradeoff: ~700MB extra temporary disk during upgrade (freed on commit). No other downsides identified -- all custom actions are guarded by (not UPGRADINGPRODUCTCODE).

Not in scope

Locked-file reboot-pending deletes (kernel-mode lock holders that MSIRMSHUTDOWN can't kill). That's a separate issue.

Test results

Scenario	Without fix (default)	With fix (`afterInstallInitialize`)
Upgrade fails mid-install	❌ WSL completely broken -- all files gone (system.vhd, wsl.exe, wslservice.exe, ...)	✅ All files automatically restored, WSL still works
User runs installer again to fix it	❌ Installer reports success but does nothing -- files still missing	✅ Not needed -- files were never lost

How the fix works (observed via filesystem monitoring):

During upgrade, old files are atomically renamed to .rbf backups (not deleted). On failure, MSI restores them from the .rbf files automatically.

Copilot

Pull request overview

This PR hardens WSL against unrecoverable failures when an MSI major upgrade fails mid-install by (1) moving old-product removal into the MSI transaction for rollback safety and (2) adding a dedicated, localized error path when required packaged VHD files (e.g., system.vhd, modules.vhd) are missing so users get an actionable message instead of a generic HCS failure.

Changes:

Adjust WiX MajorUpgrade scheduling so RemoveExistingProducts runs inside the MSI transaction (rollback restores the previous install on failure).
Introduce WSL_E_SYSTEM_DISTRO_MISSING and a localized message for missing packaged files.
Add runtime existence checks in VM startup paths and wire the new HRESULT into common error-string handling.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
msipackage/package.wix.in	Schedules `MajorUpgrade` removal to occur inside the MSI transaction for rollback protection.
src/windows/service/inc/wslservice.idl	Adds new HRESULT `WSL_E_SYSTEM_DISTRO_MISSING` (0x33).
src/windows/service/exe/WslCoreVm.cpp	Replaces debug-only asserts with production checks that throw a user-facing localized error when packaged VHDs are missing.
src/windows/service/exe/HcsVirtualMachine.cpp	Adds packaged-file existence validation before attaching boot VHDs (currently without setting a user-facing message).
src/windows/common/wslutil.cpp	Adds the new HRESULT to common error mappings and returns a localized fallback string (currently hard-coded to `system.vhd`).
localization/strings/en-US/Resources.resw	Adds `MessageSystemDistroMissing` localized string resource.

benhillis · 2026-05-13T23:50:12Z

Thanks for investigating, would it be possible to try to root cause the issue instead of a band-aid? A slightly better error message isn’t going to help users that get into this state.

Move MajorUpgrade Schedule to afterInstallInitialize so RemoveExistingProducts runs inside the MSI transaction. On upgrade failure, the old product is restored instead of leaving files permanently deleted. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

yeelam-gordon · 2026-05-18T13:26:10Z

Apologies for the earlier noise — I've cleaned this up. The PR is now a single-line MSI fix (the root cause), no runtime checks. The previous defense-in-depth changes have been removed to keep this focused on what actually prevents the data loss.

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

ptrivedi

Seems to be a righteous fix targeted towards preventing data loss. It would be good to keep an eye out at figuring out why some of these installs fail as we look at more issues.

OneBlue

Reading through https://docs.firegiant.com/wix3/xsd/wix/majorupgrade/, this appears to be low risk and should be a direct improvement in case of an upgrade failure.

Change LGTM, although if it all possible I would recommend adding a test failure that artificially fails the upgrade to validate the rollback (potentially doing something similar to what the MsixUpgradeFails() test case does)

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

+        // Restore ProductCode and reinstall cleanly for subsequent tests.
+        restoreProductCode.reset();
+        InstallMsi();
+        ValidatePackageInstalledProperly();


Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

+        auto wslExePath = m_installedPath / WSL_BINARY_NAME;
+        VERIFY_IS_TRUE(std::filesystem::exists(wslExePath));
+


+        // Verify rollback restored the old product's files.
+        VERIFY_IS_TRUE(std::filesystem::exists(wslExePath));
+


Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

+    TEST_METHOD(MsiUpgradeRollbackRestoresFiles)
+    {
+        // Remove the MSI package — mirrors the setup in MsixUpgradeFails.
+        UninstallMsi();
+        VERIFY_IS_FALSE(IsMsiPackageInstalled());


Add MsiUpgradeRollbackRestoresFiles test that validates the Schedule="afterInstallInitialize" fix by: 1. Installing an older WSL version (2.0.2) 2. Locking wsl.exe to force the upgrade to fail 3. Verifying rollback restores files and MSI registration 4. Reinstalling current version for subsequent tests Follows the same pattern as MsixUpgradeFails() but tests the MSI-to-MSI upgrade path with rollback verification. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

+    TEST_METHOD(MsiUpgradeRollbackRestoresFiles)
+    {
+        // Verify that direct MSI install via msiexec works after uninstall.
+        // This validates the test infrastructure before testing failure scenarios.
+        UninstallMsi();
+        VERIFY_IS_FALSE(IsMsiPackageInstalled());


+            std::chrono::minutes(2),
+            []() { return wil::ResultFromCaughtException() == E_ABORT; });
+
+        VERIFY_ARE_EQUAL(0L, exitCode);


+        std::wstring commandLine;
+        THROW_IF_FAILED(wil::GetSystemDirectoryW(commandLine));
+        commandLine += std::format(L"\\msiexec.exe /qn /norestart /i \"{}\" /L*V \"{}\"", m_msiPath, logPath);
+
+        LogInfo("Calling msiexec: %ls", commandLine.c_str());


Copilot AI review requested due to automatic review settings May 13, 2026 14:54

Copilot started reviewing on behalf of yeelam-gordon May 13, 2026 14:55 View session

Copilot AI reviewed May 13, 2026

View reviewed changes

Comment thread src/windows/service/exe/HcsVirtualMachine.cpp Outdated

Comment thread src/windows/common/wslutil.cpp Outdated

Comment thread src/windows/service/exe/WslCoreVm.cpp Outdated

yeelam-gordon force-pushed the fix/system-vhd-rollback-and-checks branch 2 times, most recently from 2ad3626 to 05c4925 Compare May 14, 2026 03:37

microsoft-github-policy-service Bot added the needs-author-feedback label May 15, 2026

benhillis added msix Installer issue. file system labels May 17, 2026

Copilot AI review requested due to automatic review settings May 18, 2026 03:35

yeelam-gordon force-pushed the fix/system-vhd-rollback-and-checks branch from 05c4925 to c1f0d2c Compare May 18, 2026 03:35

Copilot started reviewing on behalf of yeelam-gordon May 18, 2026 03:36 View session

Copilot AI reviewed May 18, 2026

View reviewed changes

microsoft-github-policy-service Bot removed the needs-author-feedback label May 18, 2026

Merge branch 'master' into fix/system-vhd-rollback-and-checks

144419a

yeelam-gordon marked this pull request as ready for review May 19, 2026 01:11

yeelam-gordon requested a review from a team as a code owner May 19, 2026 01:11

Copilot AI review requested due to automatic review settings May 19, 2026 01:11

Copilot started reviewing on behalf of yeelam-gordon May 19, 2026 01:13 View session

microsoft-github-policy-service Bot added the needs-author-feedback label May 19, 2026

Copilot AI reviewed May 19, 2026

View reviewed changes

Merge branch 'master' into fix/system-vhd-rollback-and-checks

3fd2e06

ptrivedi previously approved these changes May 21, 2026

View reviewed changes

OneBlue previously approved these changes Jun 2, 2026

View reviewed changes

chemwolf6922 mentioned this pull request Jun 5, 2026

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

Open

2 tasks

chemwolf6922 changed the title ~~Fix system.vhd loss during failed MSI upgrade~~ Enable rollback on install failures during update Jun 5, 2026

Copilot AI review requested due to automatic review settings June 5, 2026 09:33

yeelam-gordon dismissed OneBlue’s stale review via 9c1ad1f June 5, 2026 09:33

yeelam-gordon requested a review from Copilot June 5, 2026 09:55

Copilot started reviewing on behalf of yeelam-gordon June 5, 2026 09:55 View session

yeelam-gordon force-pushed the fix/system-vhd-rollback-and-checks branch from bb59b51 to 25ff710 Compare June 5, 2026 09:58