From 05baa8afb1caa2db5fc13e9279eb744b6a089823 Mon Sep 17 00:00:00 2001 From: Huzaifa Danish Date: Thu, 16 Jul 2026 13:07:45 -0700 Subject: [PATCH 1/3] fix(wslc): clarify WSL runtime prerequisite Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: f46e1b1d-d428-4d1b-b9c3-b83ca7b35ec2 --- docs/wsl/wsl-container-getting-started.md | 12 +++---- .../wslc/common/src/wsl_container_runner.rs | 33 ++++++++++++++++--- 2 files changed, 34 insertions(+), 11 deletions(-) diff --git a/docs/wsl/wsl-container-getting-started.md b/docs/wsl/wsl-container-getting-started.md index 3e5cdb6a9..b1d0e6255 100644 --- a/docs/wsl/wsl-container-getting-started.md +++ b/docs/wsl/wsl-container-getting-started.md @@ -11,13 +11,13 @@ MXC, which lets you run Linux containers on Windows using the WSLC SDK. | Requirement | Details | |---|---| | **Windows 11** | Required for WSL2 and the WSLC SDK | -| **WSL 2.8.1+** | See Step 1 below for installation | -| **WSLC SDK** | `wslcsdk.dll` must be in the same directory as `wxc-exec.exe` | +| **WSL 2.8.0+** | The installed WSL runtime package must meet the WSLC minimum; see Step 1 below for installation | +| **WSLC SDK** | `wslcsdk.dll` is a separate client SDK and must be in the same directory as `wxc-exec.exe` | | **Container images** | Pre-pulled or available from a registry with network access | -## Step 1 — Install WSL 2.8.1+ +## Step 1 — Install WSL 2.8.0+ -The WSLC SDK requires WSL version 2.8.1 or later. Update WSL to the latest +The WSLC SDK requires WSL version 2.8.0 or later. Update WSL to the latest version: ```powershell @@ -30,7 +30,7 @@ Verify your WSL version after updating: wsl --version ``` -The WSL version should be **2.8.1.0 or later**. If `wsl --update` does not +The WSL version should be **2.8.0.0 or later**. If `wsl --update` does not bring you to the required version, build WSL from the `master` branch: @@ -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 runtime package is missing, older than 2.8.0, or a required component is disabled | Update WSL with `wsl --update`, verify the installed version with `wsl --version`, and enable the Virtual Machine Platform optional component if required. The WSLC SDK DLL is a separate dependency and does not replace the WSL runtime package. | | `WSLC image '' not found locally` | Image was not pre-pulled, and no `imageTarPath` is set | Run `.\scripts\setup-wslc.ps1 -Image ` (or `wxc-exec.exe --setup-wslc --image `); 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 | diff --git a/src/backends/wslc/common/src/wsl_container_runner.rs b/src/backends/wslc/common/src/wsl_container_runner.rs index 4b0244729..8bb35166a 100644 --- a/src/backends/wslc/common/src/wsl_container_runner.rs +++ b/src/backends/wslc/common/src/wsl_container_runner.rs @@ -317,6 +317,24 @@ fn sdk_error(context: &str, hr: HRESULT, sdk_msg: &str) -> ScriptResponse { ScriptResponse::error(&msg) } +fn wslc_prerequisite_error(missing: WslcComponentFlags) -> String { + if missing as u32 & WslcComponentFlags::WslPackage as u32 != 0 { + return format!( + "WSLC runtime not available. Missing components: {:?}. The installed WSL \ + package must be version 2.8.0 or newer. The WSLC SDK DLL is present, but \ + the WSL runtime is missing or too old. Update WSL with `wsl --update` \ + and verify the installed version with `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) } @@ -356,11 +374,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"); @@ -1311,4 +1325,13 @@ mod tests { let result = WSLContainerRunner::detect_tar_format("/nonexistent/path.tar"); assert!(result.is_err()); } + + #[test] + fn wsl_package_prerequisite_error_explains_minimum_version() { + let message = wslc_prerequisite_error(WslcComponentFlags::WslPackage); + + assert!(message.contains("2.8.0")); + assert!(message.contains("WSLC SDK DLL is present")); + assert!(message.contains("wsl --update")); + } } From 437d24d4e04f7e40bf1146131590baf3a87316fa Mon Sep 17 00:00:00 2001 From: Huzaifa Danish Date: Thu, 16 Jul 2026 14:07:48 -0700 Subject: [PATCH 2/3] refine(wslc): simplify prerequisite guidance Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: f46e1b1d-d428-4d1b-b9c3-b83ca7b35ec2 --- docs/wsl/wsl-container-getting-started.md | 12 ++++++------ .../wslc/common/src/wsl_container_runner.rs | 15 ++------------- 2 files changed, 8 insertions(+), 19 deletions(-) diff --git a/docs/wsl/wsl-container-getting-started.md b/docs/wsl/wsl-container-getting-started.md index b1d0e6255..26bc9e2dc 100644 --- a/docs/wsl/wsl-container-getting-started.md +++ b/docs/wsl/wsl-container-getting-started.md @@ -11,13 +11,13 @@ MXC, which lets you run Linux containers on Windows using the WSLC SDK. | Requirement | Details | |---|---| | **Windows 11** | Required for WSL2 and the WSLC SDK | -| **WSL 2.8.0+** | The installed WSL runtime package must meet the WSLC minimum; see Step 1 below for installation | -| **WSLC SDK** | `wslcsdk.dll` is a separate client SDK and must be in the same directory as `wxc-exec.exe` | +| **WSL 2.8.1+** | See Step 1 below for installation | +| **WSLC SDK** | `wslcsdk.dll` must be in the same directory as `wxc-exec.exe` | | **Container images** | Pre-pulled or available from a registry with network access | -## Step 1 — Install WSL 2.8.0+ +## Step 1 — Install WSL 2.8.1+ -The WSLC SDK requires WSL version 2.8.0 or later. Update WSL to the latest +The WSLC SDK requires WSL version 2.8.1 or later. Update WSL to the latest version: ```powershell @@ -30,7 +30,7 @@ Verify your WSL version after updating: wsl --version ``` -The WSL version should be **2.8.0.0 or later**. If `wsl --update` does not +The WSL version should be **2.8.1.0 or later**. If `wsl --update` does not bring you to the required version, build WSL from the `master` branch: @@ -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 runtime package is missing, older than 2.8.0, or a required component is disabled | Update WSL with `wsl --update`, verify the installed version with `wsl --version`, and enable the Virtual Machine Platform optional component if required. The WSLC SDK DLL is a separate dependency and does not replace the WSL runtime package. | +| `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 '' not found locally` | Image was not pre-pulled, and no `imageTarPath` is set | Run `.\scripts\setup-wslc.ps1 -Image ` (or `wxc-exec.exe --setup-wslc --image `); 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 | diff --git a/src/backends/wslc/common/src/wsl_container_runner.rs b/src/backends/wslc/common/src/wsl_container_runner.rs index 8bb35166a..61e63d81f 100644 --- a/src/backends/wslc/common/src/wsl_container_runner.rs +++ b/src/backends/wslc/common/src/wsl_container_runner.rs @@ -320,10 +320,8 @@ fn sdk_error(context: &str, hr: HRESULT, sdk_msg: &str) -> ScriptResponse { fn wslc_prerequisite_error(missing: WslcComponentFlags) -> String { if missing as u32 & WslcComponentFlags::WslPackage as u32 != 0 { return format!( - "WSLC runtime not available. Missing components: {:?}. The installed WSL \ - package must be version 2.8.0 or newer. The WSLC SDK DLL is present, but \ - the WSL runtime is missing or too old. Update WSL with `wsl --update` \ - and verify the installed version with `wsl --version`.", + "WSLC runtime unavailable. Missing components: {:?}. WSL 2.8.1 or newer \ + is required. Run `wsl --update` and check `wsl --version`.", missing ); } @@ -1325,13 +1323,4 @@ mod tests { let result = WSLContainerRunner::detect_tar_format("/nonexistent/path.tar"); assert!(result.is_err()); } - - #[test] - fn wsl_package_prerequisite_error_explains_minimum_version() { - let message = wslc_prerequisite_error(WslcComponentFlags::WslPackage); - - assert!(message.contains("2.8.0")); - assert!(message.contains("WSLC SDK DLL is present")); - assert!(message.contains("wsl --update")); - } } From e0681ed2172b0c1ef4521d4db5791f3d9df36beb Mon Sep 17 00:00:00 2001 From: Huzaifa Danish Date: Mon, 20 Jul 2026 11:39:11 -0700 Subject: [PATCH 3/3] fix(wslc): inline prerequisite error Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>\nCopilot-Session: f46e1b1d-d428-4d1b-b9c3-b83ca7b35ec2 --- .../wslc/common/src/wsl_container_runner.rs | 22 +++++-------------- 1 file changed, 5 insertions(+), 17 deletions(-) diff --git a/src/backends/wslc/common/src/wsl_container_runner.rs b/src/backends/wslc/common/src/wsl_container_runner.rs index 61e63d81f..93a36291b 100644 --- a/src/backends/wslc/common/src/wsl_container_runner.rs +++ b/src/backends/wslc/common/src/wsl_container_runner.rs @@ -317,22 +317,6 @@ fn sdk_error(context: &str, hr: HRESULT, sdk_msg: &str) -> ScriptResponse { ScriptResponse::error(&msg) } -fn wslc_prerequisite_error(missing: WslcComponentFlags) -> String { - if missing as u32 & WslcComponentFlags::WslPackage as u32 != 0 { - return format!( - "WSLC runtime unavailable. Missing components: {:?}. WSL 2.8.1 or newer \ - 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) } @@ -372,7 +356,11 @@ impl WSLContainerRunner { return Err(sdk_error("WslcCanRun failed", hr, "")); } if can_run == 0 { - return Err(ScriptResponse::error(&wslc_prerequisite_error(missing))); + return Err(ScriptResponse::error(&format!( + "WSLC runtime unavailable. Missing components: {:?}. Install WSL 2.8.1 or \ + newer and run `wsl --update`.", + missing + ))); } let _ = writeln!(logger, "[WSLC] Runtime check passed");