Windows: setup fails with WSL_E_WSL_OPTIONAL_COMPONENT_REQUIRED - the "Subsystem for Linux" optional component is never enabled
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Newbie friendliness
- 55/100
Research direction
Read the -Wsl branch in contrib/windows/kiri-admin.ps1 and the WSL setup and output handling in crates/kiri-win/src/setup.rs. Start by tracing how the elevated step enables Windows features and how install_wsl() handles exit code 3010; then check how wsl_text() decodes localized output. Done means setup enables the required component, handles a restart, imports the distro, and reports readable errors.
Written by the indexing model from the issue text.
Description
Kiri version and system
0.2.1 on Windows 10 Enterprise build 19045.6456 (x64); WSL 3.0.3.0 (kernel 6.18.54.1-1); distro Kiri Linux (kiri); Microsoft-Windows-Subsystem-Linux: Disabled, VirtualMachinePlatform: Enabled
What you did
- A fresh Windows 10 22H2 PC where WSL had never been installed (
wsl.exewas not on PATH, the "Subsystem for Linux" optional component was off, Virtual Machine Platform was off). - Started Kiri 0.2.1, setup window, "Install WSL", approved the administrator prompt.
- Kiri's own elevated step ran, Windows restarted (setup's own restart step), Kiri carried on by itself, and I chose "Kiri Linux".
- Setup reached the "Add it to WSL" task and failed there.
State of the machine at that point:
PS> Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
FeatureName : Microsoft-Windows-Subsystem-Linux
State : Disabled
PS> Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform
FeatureName : VirtualMachinePlatform
State : Enabled
What happened
Problem 1 - the "Subsystem for Linux" optional component is never enabled, so "wsl --import" fails.
The setup window and %LOCALAPPDATA%\Kiri\kiri-win.log show the WSL error mangled into unreadable characters:
2026-11-15T13:48:26Z setup linux: ; O M B > 3 > ? @ 8 ; > 6 5 = 8 O B @ 5 1 C 5 B A O 4 > ? > ; = 8 B 5 ; L = K 9 : > < ? > = 5 = B ? > 4 A 8 A B 5 < K Windows 4 ; O Linux.
The same command by hand, with the message WSL actually prints:
PS> wsl --import kiri "$env:LOCALAPPDATA\Kiri\wsl\kiri" "$env:LOCALAPPDATA\Kiri\kiri-linux.tar.gz" --version 2
Для этого приложения требуется дополнительный компонент подсистемы Windows для Linux.
Установите его, выполнив команду wsl.exe --install --no-distribution
Чтобы изменения вступили в силу может потребоваться перезапустить систему.
Wsl/WSL_E_WSL_OPTIONAL_COMPONENT_REQUIRED
The cause is in contrib/windows/kiri-admin.ps1 (the -Wsl branch, the elevated step setup.rs runs as "kiri-admin.ps1 -Wsl -Msi <wsl .msi> -Sha256 <hex>"): it turns on VirtualMachinePlatform and installs the WSL MSI, but never enables the Microsoft-Windows-Subsystem-Linux optional component that "wsl --install" enables:
$vmp = (Start-Process "$env:SystemRoot\System32\dism.exe" -ArgumentList '/online', '/enable-feature', '/featurename:VirtualMachinePlatform', '/all', '/norestart' -Wait -PassThru -WindowStyle Hidden).ExitCode
if ($vmp -ne 0 -and $vmp -ne 3010) { Remove-Item -LiteralPath $dst -Force; exit 20 }
$msiexec = (Start-Process "$env:SystemRoot\System32\msiexec.exe" -ArgumentList '/i', ('"' + $dst + '"'), '/qn', '/norestart' -Wait -PassThru -WindowStyle Hidden).ExitCode
Installing the WSL MSI puts wsl.exe in place (so "wsl --version" works and setup.rs's wsl_installed() returns true), but the OS component behind it stays off on the builds where it is off by default - Windows 10 22H2 among them. Every WSL command that needs the subsystem then fails, and the import never happens.
The Ubuntu path would hit the same missing component ("wsl --install --from-file" needs the subsystem too), so this is not specific to the bundled Kiri Linux.
Problem 2 - the error message that would have named the cause is unreadable.
wsl_text() in crates/kiri-win/src/setup.rs recognises WSL's UTF-16 output only when every high byte is zero:
/// WSL's own output is UTF-16.
fn wsl_text(bytes: &[u8]) -> String {
if bytes.len() >= 2 && bytes.iter().skip(1).step_by(2).take(8).all(|&b| b == 0) {
That holds for ASCII text, but not for a localized one: 'Д' is U+0414, so in UTF-16LE its bytes are 0x14 0x04 and the high byte is 0x04, not zero. The check fails, the bytes are decoded as UTF-8, and the setup window and kiri-win.log show the garbled line quoted above instead of the message - which is the one that says what to do. The same message is readable when WSL writes it in English (Wsl/WSL_E_WSL_OPTIONAL_COMPONENT_REQUIRED came out fine), so the bug only shows up on a non-English Windows.
What you expected instead
Solution 1 - enable the optional component in the elevated step. In contrib/windows/kiri-admin.ps1, next to VirtualMachinePlatform:
$wsl = (Start-Process "$env:SystemRoot\System32\dism.exe" -ArgumentList '/online', '/enable-feature', '/featurename:Microsoft-Windows-Subsystem-Linux', '/all', '/norestart' -Wait -PassThru -WindowStyle Hidden).ExitCode
if ($wsl -ne 0 -and $wsl -ne 3010) { Remove-Item -LiteralPath $dst -Force; exit 24 }
and let a 3010 from it mean "restart", which setup already knows how to do: install_wsl() registers RunOnce\KiriSetup and shows the "Restart now" step when the elevated run returns 3010. Enabling the feature is exactly what wsl.exe --install --no-distribution does, so running that instead of the MSI (or before it) would cover it too.
Solution 2 - check for it before importing, and say so in words. In crates/kiri-win/src/setup.rs, install_linux() could check the feature before wsl --import and report "the Subsystem for Linux component is off; turn it on with wsl --install --no-distribution" instead of letting wsl.exe speak for itself, and wsl_ok() could name that case the way it names exit codes 20/21/22/23.
Solution 3 - decode WSL's UTF-16 output whatever the language. wsl_text() should recognise UTF-16LE for non-ASCII text as well. A rule that covers ASCII and Cyrillic: treat the bytes as UTF-16LE when the odd bytes are all zero or all below 0x10 (Cyrillic U+0400-U+04FF has the high byte 0x04), and drop the NULs. A more general alternative: decode as UTF-8 first, and if the result contains control characters other than whitespace, decode as UTF-16LE instead.
After any of these, setup on a PC without the subsystem component should turn it on in the same elevated step, ask for the restart it already handles, and import the distro - with no manual wsl --install and no unreadable error.
Anything else
The workaround that got me unblocked (administrator PowerShell):
dism /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
# restart Windows
wsl --import kiri "$env:LOCALAPPDATA\Kiri\wsl\kiri" "$env:LOCALAPPDATA\Kiri\kiri-linux.tar.gz" --version 2
After the restart Kiri's setup carried on by itself and everything worked: kiri 0.2.1, engine 27.5.1, docker run --rm alpine echo hello prints hello.
Two smaller notes:
kiri-linux.tar.gzships in%LOCALAPPDATA%\Kiri\, not in%LOCALAPPDATA%\Kiri\wsl\- that folder is where the distro is imported to. The manual command in the report had the wrong path for the archive; Kiri's own code gets it right (verified("kiri-linux.tar.gz")beside the exe, imported todir()/wsl/kiri).- I did not find an existing report for this: searching the repo for
WSL_E_WSL_OPTIONAL_COMPONENT_REQUIRED, "Subsystem for Linux" and "Microsoft-Windows-Subsystem-Linux" turns up nothing, andmain'skiri-admin.ps1still enables only VirtualMachinePlatform.
- Dominant language
- Rust
- Stars
- 7.5k
- Forks
- 329
- Avg merge
- 7h 48m
- Merged PRs (30d)
- 105
Getting set up
This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from libracoder/kiri
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
libracoder/kiri#364 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
libracoder/kiri#289 ·
Maintainers usually reply within 1 day
-
bug
Difficulty 4/5 3-5 days Newbie friendliness 47/100
libracoder/kiri#365 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 35/100
libracoder/kiri#362 ·
Maintainers usually reply within 1 day
-
bug
Difficulty 3/5 1-2 days Newbie friendliness 47/100
libracoder/kiri#359 ·
Maintainers usually reply within 1 day
Similar issues
-
benchmark-review
Difficulty 2/5 1-3 hours Newbie friendliness 63/100
Maintainers usually reply within 1 day
-
area:filesystem bug need-triage
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Maintainers usually reply within 1 day
-
Captions panel does not offer to show an existing transcriptPossibly taken @thedavidweng claimed this today. Open
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
CapSoftware/Cap#4276 · 1 comment ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
matrix-org/matrix-rust-sdk#7495 ·
Maintainers usually reply within 1 day