Windows: setup fails with WSL_E_WSL_OPTIONAL_COMPONENT_REQUIRED - the "Subsystem for Linux" optional component is never enabled

Open
#297 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
55/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
powershell, rust
Domain
backend, devops

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

bug
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
  1. A fresh Windows 10 22H2 PC where WSL had never been installed (wsl.exe was not on PATH, the "Subsystem for Linux" optional component was off, Virtual Machine Platform was off).
  2. Started Kiri 0.2.1, setup window, "Install WSL", approved the administrator prompt.
  3. Kiri's own elevated step ran, Windows restarted (setup's own restart step), Kiri carried on by itself, and I chose "Kiri Linux".
  4. 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.gz ships 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 to dir()/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, and main's kiri-admin.ps1 still 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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from libracoder/kiri

All issues in libracoder/kiri

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.