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.

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.

azure-pipelines · 2026-07-05T13:11:34Z

Azure Pipelines successfully started running 1 pipeline(s).

yeelam-gordon · 2026-07-06T01:23:55Z

/azp run

azure-pipelines · 2026-07-06T01:24:02Z

Azure Pipelines successfully started running 1 pipeline(s).

Copilot

Pull request overview

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

yeelam-gordon · 2026-07-06T01:56:14Z

/azp run

azure-pipelines · 2026-07-06T01:56:22Z

Azure Pipelines successfully started running 1 pipeline(s).

yeelam-gordon · 2026-07-06T02:06:10Z

/azp run

azure-pipelines · 2026-07-06T02:06:18Z

Azure Pipelines successfully started running 1 pipeline(s).

Copilot

Pull request overview

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

yeelam-gordon · 2026-07-06T04:01:38Z

/azp run

azure-pipelines · 2026-07-06T04:01:47Z

Azure Pipelines successfully started running 1 pipeline(s).

yeelam-gordon · 2026-07-06T04:15:10Z

/azp run

azure-pipelines · 2026-07-06T04:15:20Z

Azure Pipelines successfully started running 1 pipeline(s).

yeelam-gordon · 2026-07-06T04:24:17Z

/azp run

azure-pipelines · 2026-07-06T04:24:25Z

Azure Pipelines successfully started running 1 pipeline(s).

Copilot

Pull request overview

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

yeelam-gordon · 2026-07-06T12:28:48Z

Hi @benhillis @ptrivedi @OneBlue — sorry for the delay on this!

I've added the e2e rollback test as suggested. The latest commit:

Installs WSL 2.0.2 via \InstallGitHubRelease, then attempts a major upgrade with a forced failure CA (\WSL_TEST_FORCE_INSTALL_FAILURE=1) inside the MSI transaction
Asserts \wsl.exe\ and \wslservice.exe\ are restored by MSI rollback after the failed upgrade
Also adds the < InstallFinalize\ bound check, wraps the CA in \ ry/CATCH_LOG, uses \wil::scope_exit\ for cleanup, and guards the WiX condition with (not UPGRADINGPRODUCTCODE)\

All CI checks are green. Would appreciate a re-review when you get a chance — thanks!

yeelam-gordon · 2026-07-06T13:09:32Z

/azp run

azure-pipelines · 2026-07-06T13:09:41Z

Azure Pipelines successfully started running 1 pipeline(s).

OneBlue

LGTM, two minor comments and

Add WslTestForceInstallFailure deferred CA that returns ERROR_INSTALL_FAILURE when WSL_TEST_FORCE_INSTALL_FAILURE=1 is passed to msiexec. Sequenced after FinalizeInstall inside the transaction so MSI rollback restores files. New MsiUpgradeFailureRestoresFiles test installs the MSI, attempts an upgrade with the forced failure, then asserts wsl.exe and wslservice.exe survived. Also fixes MsiRemoveExistingProductsScheduledInsideTransaction per review: - Use MSI_NULL_INTEGER instead of -1 for null sequence detection - Drop redundant InstallFinalize bound check Co-authored-by: Copilot <[email protected]>

yeelam-gordon · 2026-07-11T00:30:59Z

/azp run

azure-pipelines · 2026-07-11T00:31:07Z

Azure Pipelines successfully started running 1 pipeline(s).

yeelam-gordon · 2026-07-11T00:31:48Z

Thanks @OneBlue! Both nits addressed:

Added ValidateInstalledVersion(L"2.0.2") after rollback — confirms the restored package reports the correct version and is functional.
Gated with OFFICIAL_BUILD — the CA, WiX sequencing, and property are wrapped in <?if "${OFFICIAL_BUILD}" != "TRUE" ?>. C++ uses #ifndef WSL_OFFICIAL_BUILD, and the test skips on official builds. The .def export is replaced with __declspec(dllexport) so the linker doesn't error when the function is absent.

Tests pass locally. CI triggered.

Copilot

Pull request overview

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

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

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

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 stale reviews from OneBlue and ptrivedi via 9c1ad1f June 5, 2026 09:33

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

Copilot AI reviewed Jun 5, 2026

View reviewed changes

Comment thread test/windows/InstallerTests.cpp Outdated

Comment thread test/windows/InstallerTests.cpp Outdated

Comment thread test/windows/InstallerTests.cpp Outdated

Copilot AI review requested due to automatic review settings July 6, 2026 01:22

yeelam-gordon force-pushed the fix/system-vhd-rollback-and-checks branch from eec7985 to 1995224 Compare July 6, 2026 01:22

Copilot started reviewing on behalf of yeelam-gordon July 6, 2026 01:23 View session

Copilot AI reviewed Jul 6, 2026

View reviewed changes

Comment thread test/windows/InstallerTests.cpp

Comment thread test/windows/InstallerTests.cpp

yeelam-gordon force-pushed the fix/system-vhd-rollback-and-checks branch from 1995224 to 1c778d3 Compare July 6, 2026 01:55

Copilot AI reviewed Jul 6, 2026

View reviewed changes

Comment thread test/windows/InstallerTests.cpp

Copilot AI reviewed Jul 6, 2026

View reviewed changes

Comment thread test/windows/InstallerTests.cpp

Comment thread test/windows/InstallerTests.cpp

OneBlue previously approved these changes Jul 9, 2026

View reviewed changes

Comment thread test/windows/InstallerTests.cpp

Comment thread msipackage/package.wix.in

Copilot AI reviewed Jul 11, 2026

View reviewed changes

OneBlue approved these changes Jul 11, 2026

View reviewed changes

Uh oh!

Conversation

yeelam-gordon commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Fix: all installed files lost on failed MSI upgrade

Problem

Fix

Not in scope

Test results

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

benhillis commented May 13, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

yeelam-gordon commented May 18, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

ptrivedi left a comment

Choose a reason for hiding this comment

Uh oh!

OneBlue left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

azure-pipelines Bot commented Jul 5, 2026

Uh oh!

yeelam-gordon commented Jul 6, 2026

Uh oh!

azure-pipelines Bot commented Jul 6, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

yeelam-gordon commented Jul 6, 2026

Uh oh!

azure-pipelines Bot commented Jul 6, 2026

Uh oh!

yeelam-gordon commented Jul 6, 2026

Uh oh!

azure-pipelines Bot commented Jul 6, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

yeelam-gordon commented Jul 6, 2026

Uh oh!

azure-pipelines Bot commented Jul 6, 2026

Uh oh!

yeelam-gordon commented Jul 6, 2026

Uh oh!

azure-pipelines Bot commented Jul 6, 2026

Uh oh!

yeelam-gordon commented Jul 6, 2026

Uh oh!

azure-pipelines Bot commented Jul 6, 2026

Uh oh!

yeelam-gordon commented May 13, 2026 •

edited

Loading