Skip to content

fix(wslc): clarify WSL runtime prerequisite #656

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
huzaifa-d wants to merge 2 commits into
base: main
Choose a base branch
from
Open

fix(wslc): clarify WSL runtime prerequisite #656

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
05baa8a
fix(wslc): clarify WSL runtime prerequisite
huzaifa-msft Jul 16, 2026
437d24d
refine(wslc): simplify prerequisite guidance
huzaifa-msft Jul 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/wsl/wsl-container-getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -238,7 +238,7 @@ the container.
|---|---|---|
| `WSLC backend not compiled` | Binary built without `--features wslc` | Rebuild with `build.bat --with-wslc` |
| `Failed to load wslcsdk.dll` | DLL not in same directory as `wxc-exec.exe` | Copy `wslcsdk.dll` next to the binary |
| `WSLC runtime not available` | WSL version too old or missing components | Update WSL with `wsl --update` or build from the [WSL repo](https://github.com/microsoft/WSL/tree/feature/wsl-for-apps) |
| `WSLC runtime not available` | WSL is too old or missing components | Update WSL with `wsl --update` and verify the version with `wsl --version` |
| `WSLC image '<name>' not found locally` | Image was not pre-pulled, and no `imageTarPath` is set | Run `.\scripts\setup-wslc.ps1 -Image <name>` (or `wxc-exec.exe --setup-wslc --image <name>`); match the `-StoragePath` to your config's `experimental.wslc.storagePath` if set |
| `WSLC is an experimental feature` | Missing `--experimental` flag | Add `--experimental` to CLI or `{ experimental: true }` in SDK |
| `experimental mode` error in SDK | `SandboxSpawnOptions.experimental` not set | Pass `{ experimental: true }` to spawn functions |
Expand Down
22 changes: 17 additions & 5 deletions src/backends/wslc/common/src/wsl_container_runner.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -317,6 +317,22 @@ fn sdk_error(context: &str, hr: HRESULT, sdk_msg: &str) -> ScriptResponse {
ScriptResponse::error(&msg)
}

fn wslc_prerequisite_error(missing: WslcComponentFlags) -> String {

@MGudgin MGudgin Jul 17, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new helper has two user-facing message branches, but this PR adds no tests for either one. Please add table-driven tests covering WslPackage, VirtualMachinePlatform, and their combined value, asserting the version and remediation guidance selected for each case.

if missing as u32 & WslcComponentFlags::WslPackage as u32 != 0 {

@MGudgin MGudgin Jul 17, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

WslcComponentFlags is a fieldless repr(u32) enum, but wslcsdk.h declares it as combinable flags. WslcCanRun can therefore return 3 when both components are missing, which is not a valid Rust enum discriminant and causes undefined behavior when read here. Please represent this FFI type as a transparent integer-backed bitmask and add coverage for combined values.

return format!(
"WSLC runtime unavailable. Missing components: {:?}. WSL 2.8.1 or newer \

@MGudgin MGudgin Jul 17, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This string says 'runtime unavailable', the one at line 330 says 'runtime not available' as does line 241 of the .md file. Let's make them consistent.

@SohamDas2021 SohamDas2021 Jul 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Jfyi, we are moving to the public release of 2.9 soon. That is the minimum publicly available version.

is required. Run `wsl --update` and check `wsl --version`.",
missing
);
}

format!(
"WSLC runtime not available. Missing components: {:?}. Ensure WSL2 and the \
WSLC SDK are installed.",
missing
)
}

impl ScriptRunner for WSLContainerRunner {
fn execute(&mut self, request: &ExecutionRequest, logger: &mut Logger) -> ScriptResponse {
unsafe { self.run_internal(request, logger) }
Expand Down Expand Up @@ -356,11 +372,7 @@ impl WSLContainerRunner {
return Err(sdk_error("WslcCanRun failed", hr, ""));
}
if can_run == 0 {
return Err(ScriptResponse::error(&format!(
"WSLC runtime not available. Missing components: {:?}. \
Ensure WSL2 and the WSLC SDK are installed.",
missing
)));
return Err(ScriptResponse::error(&wslc_prerequisite_error(missing)));
}
let _ = writeln!(logger, "[WSLC] Runtime check passed");

Expand Down
Loading