Investigating WSL Development Problems by Boundary

WSL provides a Linux development environment on Windows.

Problems at the Windows–Linux boundary can look like application failures.

Missing commands, unavailable explorer.exe, unstable encoding, and /mnt/c I/O errors are common examples.

These notes turn observations from trying Ubuntu 24.04 and 26.04 under WSL into a reusable troubleshooting process.

Behavior varies by WSL version and Windows build, so separate environment-specific observations from official behavior.

Establish the environment first

When a problem appears, identify which distribution is running, under which WSL mode, and from where it was launched.

On Windows:

wsl --status
wsl --version
wsl --list --verbose

Inside Linux:

cat /etc/os-release
uname -a
printf '%s\n' "$PATH"
locale
pwd

Check whether the system uses WSL 1 or WSL 2.

Compare the default distribution with the one actually launched.

Check whether the project lives in the Linux filesystem or under /mnt/c.

Also check whether Windows PATH entries were imported into Linux.

“WSL does not work” can mean distribution startup, shell configuration, or filesystem failure.

When `compinit` or completion breaks

After replacing a distribution or reorganizing zsh configuration, inspect compinit, fpath, .zcompdump, and plugin caches.

Changing several of them at once makes the cause difficult to isolate.

Start zsh without plugins or user configuration.

zsh -f

# Test completion in the minimal environment
autoload -Uz compinit
compinit
compaudit

If zsh -f and minimal compinit work, inspect .zshrc, fpath, and plugin initialization before the WSL binary.

Restore normal configuration in this order:

Core shell settings
fpath and completion initialization
Plugin manager
Atuin, prompt, and other additions

Inspect only the owners and permissions named by compaudit.

Avoid broad recursive chmod operations that change unrelated files.

Decide on locale early

An unset locale can cause warnings, unexpected sorting, mojibake, and Python or Ruby I/O problems.

Displaying Japanese is separate from making the system locale Japanese.

Prioritize stable UTF-8 behavior in the development environment.

locale
locale charmap

Using C.UTF-8 as the default and choosing application display languages separately can be easier to operate.

Localized error messages can be harder for machine-processing scripts to classify.

After changes, open a new shell and check:

printf '%s\n' "$LANG" "$LC_ALL" "$LC_CTYPE"
locale charmap

If the settings do not apply, inspect /etc/default/locale, shell startup files, Windows Terminal profiles, and SSH configuration.

Unconditionally overriding locale variables in .zshrc also affects non-interactive shells.

When `explorer.exe` cannot be found

WSL interoperability allows Windows executables to run from a Linux shell.

Microsoft’s WSL interop documentation includes:

explorer.exe .

For command not found, first check that the .exe suffix is present.

Then check imported Windows PATH entries:

printf '%s\n' "$PATH" | tr ':' '\n' | grep -i '/mnt/c/Windows'
command -v explorer.exe

If Windows PATH is absent, inspect /etc/profile and .zshrc for assignments that replace $PATH rather than preserving it.

Import only the Windows commands required by the environment and keep the policy predictable.

Adding every Windows PATH entry is not automatically the correct fix.

`/mnt/c` I/O and project location

WSL 2 has a performance cost when operations cross Linux and Windows filesystems.

Microsoft recommends keeping projects used by Linux tools in WSL’s filesystem.

The difference is visible especially with:

Node.js projects containing node_modules
Git operations over many small files
Rust and Go builds
Development servers watching many files

For a project primarily using Linux CLIs:

~/projects/my-app        # Run Git, Node, and cargo inside WSL

Open it from a Windows editor through \\wsl$ or \\wsl.localhost.

When Windows tools are primary, keeping the project on Windows and using WSL as a secondary environment is also valid.

Do not immediately delete files or change mount settings after an I/O error on /mnt/c.

Check in this order:

Can Windows open the same path?
Can WSL read and write under /tmp or $HOME?
Confirm the distribution with wsl --list --verbose
Stop running work, run wsl --shutdown, and restart
Update WSL
If only one drive fails, inspect Windows locks, permissions, and disk state

Cross-filesystem access includes a translation layer.

I/O failures and performance problems are different, but both can originate at this boundary.

Deciding whether to return to an older Ubuntu version

More problems after an Ubuntu migration do not automatically mean that the distribution is defective.

If shell plugins, PATH, locale, packages, and configuration changed together, reduce the change set first.

When development is blocked by tool or dependency support, returning to a known stable version can be reasonable.

Before deleting or re-registering anything, save:

Required files under ~/.config and ~/.local
SSH keys and permissions
Git configuration and authentication method
A list of installed packages
Projects and data existing only inside WSL
Distribution settings such as /etc/wsl.conf

From Windows, export a whole distribution with:

wsl --export <distribution-name> <backup-path.tar>

Verify the destination, individual files, and restore procedure before unregistering or re-registering.

Removing a distribution can remove its files.

Do not delete it without verifying a backup and export.

Returning to a known version is environment pinning in service of development work, not a failure.

Symptom checklist

Symptom	Check first	Then check
Broken completion	`zsh -f`, `compinit`, `compaudit`, `fpath`	Restore plugins one at a time
Mojibake or locale warning	`locale`, `locale charmap`	`/etc/default/locale` and shell settings
Missing `explorer.exe`	Suffix, `$PATH`, `command -v`	PATH replacement in `/etc/profile`
Slow `/mnt/c`	Project location	Compare after moving to WSL `$HOME`
`/mnt/c` I/O error	Windows access and another WSL path	`wsl --shutdown`, WSL update
Distribution will not start	`wsl --status`, `wsl -l -v`	Virtualization, distribution, logs

Do not make a full WSL reinstall the first response.

Rebuilding can remove the symptom while also removing the reproduction conditions and configuration differences.

Summary

WSL diagnosis becomes difficult when looking only at Linux or only at Windows.

Separate the distribution from WSL itself.

Separate Linux PATH from Windows PATH.

Separate the Linux filesystem from /mnt/c.

Separate the shell from its plugins.

Keep Linux-tool projects in WSL.

When Windows interoperability is required, verify PATH and .exe invocation.

Before reverting an environment, back up data and settings.

Establish the environment first

When compinit or completion breaks