fix(service): improve error diagnostics for distribution start failures#14442
fix(service): improve error diagnostics for distribution start failures#14442yeelam-gordon wants to merge 8 commits intomicrosoft:masterfrom
Conversation
Adds more descriptive error messages and logging for CreateInstance/E_FAIL failures (error code 16, step 2). Users now get actionable guidance instead of opaque error codes. Fixes microsoft#14045 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
This PR improves the error diagnostics when WSL fails to start a distribution, addressing the opaque "Error code: 16, failed step: 2 / E_FAIL" message reported in issue #14045. The changes add human-readable step descriptions to error messages, introduce a specific error path for mount-disk failures with actionable guidance, and add ETL trace breadcrumbs throughout the CreateInstance flow.
Changes:
- Enriched error messages with step descriptions (e.g., "mount the distribution's virtual disk") and reordered format arguments to lead with the failure step
- Added a dedicated mount-disk failure error path with guidance to check
.wslconfigsettings - Added WSL_LOG breadcrumbs at key points in
CreateInstance(disk attach begin/end, message sent, awaiting guest result)
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
src/windows/service/exe/WslCoreVm.cpp |
Added four WSL_LOG trace events around disk attach and message-send steps in CreateInstance |
src/windows/service/exe/WslCoreInstance.cpp |
Added CreateInstanceStepDescription helper, detailed logging of guest results, mount-disk-specific error branch with ExecutionContext, and updated error message format arguments |
localization/strings/en-US/Resources.resw |
Updated MessageDistributionFailedToStart format, added MessageDistributionFailedToStartMountDisk and five step-description strings |
You can also share your feedback on Copilot code review. Take the survey.
…nostics Add DiagnosticsTests.cpp with TAEF tests covering: - Enum-to-string mapping for all LX_MINI_CREATE_INSTANCE_STEP values - Default/unknown fallback behavior - LxInitCreateInstanceStepLaunchInit alias (same value as LaunchSystemDistro) - Distinct descriptions for each known step - Error message format validation (3-parameter format) - MountDisk-specific message includes .wslconfig/swapFile guidance - Generic vs mount-disk message differentiation - EINVAL/EUCLEAN constant documentation Extract CreateInstanceStepDescription from anonymous namespace to DiagnosticsHelpers.h for testability. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
This PR improves diagnostics when a WSL distribution fails to start (notably the opaque “Error code: 16 … CreateInstance/E_FAIL”), adding more actionable user-facing error messages and additional service-side breadcrumbs for CreateInstance.
Changes:
- Add localized step descriptions and new formatted error messages (including mount-disk-specific guidance).
- Emit additional TraceLogging breadcrumbs around disk attach and CreateInstance guest result handling.
- Add Windows unit tests covering step-description mapping and message formatting.
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 |
|---|---|
| test/windows/DiagnosticsTests.cpp | New unit tests for step-to-description mapping and formatted failure messages. |
| test/windows/CMakeLists.txt | Adds the new diagnostics test file to the wsltests build. |
| src/windows/service/exe/WslCoreVm.cpp | Adds CreateInstance TraceLogging breadcrumbs around disk attach and message send. |
| src/windows/service/exe/WslCoreInstance.cpp | Logs guest result details and emits improved user-facing error messages (generic and mount-disk-specific). |
| src/windows/service/exe/DiagnosticsHelpers.h | Adds CreateInstanceStepDescription helper that maps failure step enums to localized strings. |
| localization/strings/en-US/Resources.resw | Updates/extends localized strings for improved diagnostics and step descriptions. |
- Add target_include_directories for src/windows/service/exe so DiagnosticsHelpers.h is resolvable from the wsltests target - Remove PR number reference from DiagnosticsTests.cpp header comment Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
| <data name="MessageDistributionFailedToStart" xml:space="preserve"> | ||
| <value>The distribution failed to start. Error code: {}, failure step: {}</value> | ||
| <value>The distribution failed to start. Failure step: {} ({}). Linux error code: {}.</value> | ||
| <comment>{FixedPlaceholder="{}"}Command line arguments, file names and string inserts should not be translated</comment> |
There was a problem hiding this comment.
MessageDistributionFailedToStart was changed from 2 to 3 {} inserts, but other locale Resources.resw files still have the old 2-insert format (e.g., fr-FR/zh-CN). The tools/devops/validate-localization.py step in CI compares insert counts across locales and will fail on this mismatch. Please update the MessageDistributionFailedToStart entry in all localization/strings/*/Resources.resw files to have 3 inserts (even if the translation is temporarily copied from en-US) so validation passes.
| <data name="MessageDistributionFailedToStart" xml:space="preserve"> | ||
| <value>无法启动分发。错误代码： {}，失败步骤： {}</value> | ||
| <value>The distribution failed to start. Failure step: {} ({}). Linux error code: {}.</value> | ||
| <comment>{FixedPlaceholder="{}"}Command line arguments, file names and string inserts should not be translated</comment> | ||
| </data> | ||
| <data name="MessageDiskCorrupted" xml:space="preserve"> | ||
| <data name="MessageDistributionFailedToStartMountDisk" xml:space="preserve"> |
There was a problem hiding this comment.
The zh-CN resource values for the new/updated distribution-start diagnostics (MessageDistributionFailedToStart, the mount-disk variant, and the step-description strings) are now in English. This regresses localized UX for Chinese users (these strings were previously translated). Please provide zh-CN translations that preserve the three {} placeholders (and locked tokens like .wslconfig / swapFile), or coordinate with localization so these entries aren’t shipped as English in the zh-CN resource file.
| <data name="MessageDistributionFailedToStart" xml:space="preserve"> | ||
| <value>Échec du démarrage de distribution. Code d’erreur : {}, étape d’échec : {}</value> | ||
| <value>The distribution failed to start. Failure step: {} ({}). Linux error code: {}.</value> | ||
| <comment>{FixedPlaceholder="{}"}Command line arguments, file names and string inserts should not be translated</comment> | ||
| </data> | ||
| <data name="MessageDiskCorrupted" xml:space="preserve"> | ||
| <data name="MessageDistributionFailedToStartMountDisk" xml:space="preserve"> |
There was a problem hiding this comment.
The fr-FR resource values for the new/updated distribution-start diagnostics (generic failure, mount-disk guidance, and step-description strings) are currently English. This is a localization regression for French UI and will ship English text to fr-FR users. Please provide French translations that keep the three {} placeholders and locked tokens unchanged, or ensure these entries go through the standard localization workflow before release.
Update MessageDistributionFailedToStart from 2 to 3 inserts in all non-en-US Resources.resw files. Add new resource entries (MessageDistributionFailedToStartMountDisk, MessageCreateInstanceStep*) using en-US text as placeholder pending translation. This fixes the insert-count mismatch that would fail validate-localization.py in CI. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
yeelam-gordon
force-pushed
the
workitem/14045-improve-error-code-16-diagnostics
branch
from
2025994 to
a12145f
Compare
Define WSL_E_DISTRO_START_FAILED (0x80040333) and WSL_E_DISTRO_MOUNT_FAILED (0x80040334) to replace generic E_FAIL in CreateInstance error paths. This makes distro-start failures distinguishable in telemetry: - WSL_E_DISTRO_MOUNT_FAILED: mount-disk failures (user-actionable, typically caused by .wslconfig settings) - WSL_E_DISTRO_START_FAILED: other start failures (generic fallback) Both can now be filtered or suppressed in reliability dashboards independently, similar to WSL_E_INVALID_USAGE. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
| <data name="MessageDistributionFailedToStart" xml:space="preserve"> | ||
| <value>Spuštění distribuce se nezdařilo. Kód chyby: {}, krok selhání: {}</value> | ||
| <value>The distribution failed to start. Failure step: {} ({}). Linux error code: {}.</value> | ||
| <comment>{FixedPlaceholder="{}"}Command line arguments, file names and string inserts should not be translated</comment> |
There was a problem hiding this comment.
This locale resource now contains an English value for MessageDistributionFailedToStart (and related new strings). That’s a localization regression for cs-CZ. Please provide a Czech translation with the updated 3 placeholders, or remove the locale-specific entry so the system can fall back to en-US until translation is available.
| <data name="MessageDistributionFailedToStart" xml:space="preserve"> | ||
| <value>Distributionen kunne ikke startes. Fejlkode: {}, fejltrin: {}</value> | ||
| <value>The distribution failed to start. Failure step: {} ({}). Linux error code: {}.</value> | ||
| <comment>{FixedPlaceholder="{}"}Command line arguments, file names and string inserts should not be translated</comment> |
There was a problem hiding this comment.
This locale resource now contains an English value for MessageDistributionFailedToStart (and related new strings). That’s a localization regression for da-DK. Please provide a Danish translation with the updated 3 placeholders, or remove the locale-specific entry so the system can fall back to en-US until translation is available.
| <value>The distribution failed to start. Failure step: {} ({}). Linux error code: {}.</value> | ||
| <comment>{FixedPlaceholder="{}"}Command line arguments, file names and string inserts should not be translated</comment> | ||
| </data> | ||
| <data name="MessageDistributionFailedToStartMountDisk" xml:space="preserve"> | ||
| <value>The distribution failed to start because WSL could not mount the distribution's virtual disk. Failure step: {} ({}). Linux error code: {}. | ||
| Check the distribution's disk and any disk-related settings in .wslconfig, such as 'swapFile', before trying again.</value> | ||
| <comment>{FixedPlaceholder="{}"}{Locked=".wslconfig"}{Locked="swapFile"}Command line arguments, file names and string inserts should not be translated</comment> | ||
| </data> | ||
| <data name="MessageCreateInstanceStepFormatDisk" xml:space="preserve"> | ||
| <value>format the distribution's virtual disk</value> | ||
| </data> | ||
| <data name="MessageCreateInstanceStepMountDisk" xml:space="preserve"> | ||
| <value>mount the distribution's virtual disk</value> | ||
| </data> | ||
| <data name="MessageCreateInstanceStepLaunchDistribution" xml:space="preserve"> | ||
| <value>launch the distribution</value> |
There was a problem hiding this comment.
This locale resource now contains an English value for MessageDistributionFailedToStart (and related new strings). That’s a localization regression for de-DE. Please provide a German translation with the updated 3 placeholders, or remove the locale-specific entry so the system can fall back to en-US until translation is available.
| <value>The distribution failed to start. Failure step: {} ({}). Linux error code: {}.</value> | |
| <comment>{FixedPlaceholder="{}"}Command line arguments, file names and string inserts should not be translated</comment> | |
| </data> | |
| <data name="MessageDistributionFailedToStartMountDisk" xml:space="preserve"> | |
| <value>The distribution failed to start because WSL could not mount the distribution's virtual disk. Failure step: {} ({}). Linux error code: {}. | |
| Check the distribution's disk and any disk-related settings in .wslconfig, such as 'swapFile', before trying again.</value> | |
| <comment>{FixedPlaceholder="{}"}{Locked=".wslconfig"}{Locked="swapFile"}Command line arguments, file names and string inserts should not be translated</comment> | |
| </data> | |
| <data name="MessageCreateInstanceStepFormatDisk" xml:space="preserve"> | |
| <value>format the distribution's virtual disk</value> | |
| </data> | |
| <data name="MessageCreateInstanceStepMountDisk" xml:space="preserve"> | |
| <value>mount the distribution's virtual disk</value> | |
| </data> | |
| <data name="MessageCreateInstanceStepLaunchDistribution" xml:space="preserve"> | |
| <value>launch the distribution</value> | |
| <value>Die Distribution konnte nicht gestartet werden. Fehlerschritt: {} ({}). Linux-Fehlercode: {}.</value> | |
| <comment>{FixedPlaceholder="{}"}Command line arguments, file names and string inserts should not be translated</comment> | |
| </data> | |
| <data name="MessageDistributionFailedToStartMountDisk" xml:space="preserve"> | |
| <value>Die Distribution konnte nicht gestartet werden, weil WSL das virtuelle Laufwerk der Distribution nicht einhängen konnte. Fehlerschritt: {} ({}). Linux-Fehlercode: {}. | |
| Überprüfen Sie vor einem erneuten Versuch das Laufwerk der Distribution und alle laufwerksbezogenen Einstellungen in .wslconfig, wie z. B. 'swapFile'.</value> | |
| <comment>{FixedPlaceholder="{}"}{Locked=".wslconfig"}{Locked="swapFile"}Command line arguments, file names and string inserts should not be translated</comment> | |
| </data> | |
| <data name="MessageCreateInstanceStepFormatDisk" xml:space="preserve"> | |
| <value>das virtuelle Laufwerk der Distribution formatieren</value> | |
| </data> | |
| <data name="MessageCreateInstanceStepMountDisk" xml:space="preserve"> | |
| <value>das virtuelle Laufwerk der Distribution einhängen</value> | |
| </data> | |
| <data name="MessageCreateInstanceStepLaunchDistribution" xml:space="preserve"> | |
| <value>die Distribution starten</value> |
| <data name="MessageDistributionFailedToStart" xml:space="preserve"> | ||
| <value>No se pudo iniciar la distribución. Código de error: {}, paso de error: {}</value> | ||
| <value>The distribution failed to start. Failure step: {} ({}). Linux error code: {}.</value> | ||
| <comment>{FixedPlaceholder="{}"}Command line arguments, file names and string inserts should not be translated</comment> |
There was a problem hiding this comment.
This locale resource now contains an English value for MessageDistributionFailedToStart (and related new strings). That’s a localization regression for es-ES. Please provide a Spanish translation with the updated 3 placeholders, or remove the locale-specific entry so the system can fall back to en-US until translation is available.
| <data name="MessageDistributionFailedToStart" xml:space="preserve"> | ||
| <value>Échec du démarrage de distribution. Code d’erreur : {}, étape d’échec : {}</value> | ||
| <value>The distribution failed to start. Failure step: {} ({}). Linux error code: {}.</value> | ||
| <comment>{FixedPlaceholder="{}"}Command line arguments, file names and string inserts should not be translated</comment> |
There was a problem hiding this comment.
This locale resource now contains an English value for MessageDistributionFailedToStart (and related new strings). That’s a localization regression for fr-FR. Please provide a French translation with the updated 3 placeholders, or remove the locale-specific entry so the system can fall back to en-US until translation is available.
| <data name="MessageDistributionFailedToStart" xml:space="preserve"> | ||
| <value>Не удалось запустить распространение. Код ошибки: {}, шаг сбоя: {}</value> | ||
| <value>The distribution failed to start. Failure step: {} ({}). Linux error code: {}.</value> | ||
| <comment>{FixedPlaceholder="{}"}Command line arguments, file names and string inserts should not be translated</comment> |
There was a problem hiding this comment.
This locale resource now contains an English value for MessageDistributionFailedToStart (and related new strings). That’s a localization regression for ru-RU. Please provide a Russian translation with the updated 3 placeholders, or remove the locale-specific entry so the system can fall back to en-US until translation is available.
| <data name="MessageDistributionFailedToStart" xml:space="preserve"> | ||
| <value>Det gick inte att starta distributionen. Felkod: {}, felsteg: {}</value> | ||
| <value>The distribution failed to start. Failure step: {} ({}). Linux error code: {}.</value> | ||
| <comment>{FixedPlaceholder="{}"}Command line arguments, file names and string inserts should not be translated</comment> |
There was a problem hiding this comment.
This locale resource now contains an English value for MessageDistributionFailedToStart (and related new strings). That’s a localization regression for sv-SE. Please provide a Swedish translation with the updated 3 placeholders, or remove the locale-specific entry so the system can fall back to en-US until translation is available.
| <data name="MessageDistributionFailedToStart" xml:space="preserve"> | ||
| <value>Dağıtım başlatılamadı. Hata kodu: {}, hata adımı: {}</value> | ||
| <value>The distribution failed to start. Failure step: {} ({}). Linux error code: {}.</value> | ||
| <comment>{FixedPlaceholder="{}"}Command line arguments, file names and string inserts should not be translated</comment> |
There was a problem hiding this comment.
This locale resource now contains an English value for MessageDistributionFailedToStart (and related new strings). That’s a localization regression for tr-TR. Please provide a Turkish translation with the updated 3 placeholders, or remove the locale-specific entry so the system can fall back to en-US until translation is available.
| <data name="MessageDistributionFailedToStart" xml:space="preserve"> | ||
| <value>无法启动分发。错误代码： {}，失败步骤： {}</value> | ||
| <value>The distribution failed to start. Failure step: {} ({}). Linux error code: {}.</value> | ||
| <comment>{FixedPlaceholder="{}"}Command line arguments, file names and string inserts should not be translated</comment> |
There was a problem hiding this comment.
This locale resource now contains an English value for MessageDistributionFailedToStart (and related new strings). That’s a localization regression for zh-CN. Please provide a Simplified Chinese translation with the updated 3 placeholders, or remove the locale-specific entry so the system can fall back to en-US until translation is available.
| <value>The distribution failed to start. Failure step: {} ({}). Linux error code: {}.</value> | ||
| <comment>{FixedPlaceholder="{}"}Command line arguments, file names and string inserts should not be translated</comment> | ||
| </data> | ||
| <data name="MessageDistributionFailedToStartMountDisk" xml:space="preserve"> | ||
| <value>The distribution failed to start because WSL could not mount the distribution's virtual disk. Failure step: {} ({}). Linux error code: {}. | ||
| Check the distribution's disk and any disk-related settings in .wslconfig, such as 'swapFile', before trying again.</value> | ||
| <comment>{FixedPlaceholder="{}"}{Locked=".wslconfig"}{Locked="swapFile"}Command line arguments, file names and string inserts should not be translated</comment> | ||
| </data> | ||
| <data name="MessageCreateInstanceStepFormatDisk" xml:space="preserve"> | ||
| <value>format the distribution's virtual disk</value> | ||
| </data> | ||
| <data name="MessageCreateInstanceStepMountDisk" xml:space="preserve"> | ||
| <value>mount the distribution's virtual disk</value> | ||
| </data> | ||
| <data name="MessageCreateInstanceStepLaunchDistribution" xml:space="preserve"> | ||
| <value>launch the distribution</value> |
There was a problem hiding this comment.
This locale resource now contains an English value for MessageDistributionFailedToStart (and related new strings). That’s a localization regression for zh-TW. Please provide a Traditional Chinese translation with the updated 3 placeholders, or remove the locale-specific entry so the system can fall back to en-US until translation is available.
| <value>The distribution failed to start. Failure step: {} ({}). Linux error code: {}.</value> | |
| <comment>{FixedPlaceholder="{}"}Command line arguments, file names and string inserts should not be translated</comment> | |
| </data> | |
| <data name="MessageDistributionFailedToStartMountDisk" xml:space="preserve"> | |
| <value>The distribution failed to start because WSL could not mount the distribution's virtual disk. Failure step: {} ({}). Linux error code: {}. | |
| Check the distribution's disk and any disk-related settings in .wslconfig, such as 'swapFile', before trying again.</value> | |
| <comment>{FixedPlaceholder="{}"}{Locked=".wslconfig"}{Locked="swapFile"}Command line arguments, file names and string inserts should not be translated</comment> | |
| </data> | |
| <data name="MessageCreateInstanceStepFormatDisk" xml:space="preserve"> | |
| <value>format the distribution's virtual disk</value> | |
| </data> | |
| <data name="MessageCreateInstanceStepMountDisk" xml:space="preserve"> | |
| <value>mount the distribution's virtual disk</value> | |
| </data> | |
| <data name="MessageCreateInstanceStepLaunchDistribution" xml:space="preserve"> | |
| <value>launch the distribution</value> | |
| <value>散發版無法啟動。失敗步驟：{} ({})。Linux 錯誤碼：{}。</value> | |
| <comment>{FixedPlaceholder="{}"}Command line arguments, file names and string inserts should not be translated</comment> | |
| </data> | |
| <data name="MessageDistributionFailedToStartMountDisk" xml:space="preserve"> | |
| <value>WSL 無法掛接散發版的虛擬磁碟，因此散發版無法啟動。失敗步驟：{} ({})。Linux 錯誤碼：{}。 | |
| 在重試之前，請先檢查散發版的磁碟，以及 .wslconfig 中與磁碟相關的設定 (例如 'swapFile')。</value> | |
| <comment>{FixedPlaceholder="{}"}{Locked=".wslconfig"}{Locked="swapFile"}Command line arguments, file names and string inserts should not be translated</comment> | |
| </data> | |
| <data name="MessageCreateInstanceStepFormatDisk" xml:space="preserve"> | |
| <value>格式化散發版的虛擬磁碟</value> | |
| </data> | |
| <data name="MessageCreateInstanceStepMountDisk" xml:space="preserve"> | |
| <value>掛接散發版的虛擬磁碟</value> | |
| </data> | |
| <data name="MessageCreateInstanceStepLaunchDistribution" xml:space="preserve"> | |
| <value>啟動散發版</value> |
Summary of the Pull Request
Improves error diagnostics for the opaque 'Error code: 16, failed step: 2 / E_FAIL' when WSL fails to start a distribution. Changes include:
PR Checklist
Validation Steps Performed
Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com