lima-vm/lima · error

failed to run `wsl.exe --distribution %s`: %w (out=%#q)

Error message

failed to run `wsl.exe --distribution %s`: %w (out=%#q)

What it means

startVM runs `wsl.exe --distribution <distroName>` to boot the Lima-managed WSL distro. If wsl.exe exits non-zero, the driver wraps the error plus the UTF-16LE decoded output in this message. It means WSL itself refused or failed to start the distribution.

Source

Thrown at pkg/driver/wsl2/vm_windows.go:34

	"strings"

	"github.com/sirupsen/logrus"

	"github.com/lima-vm/lima/v2/pkg/executil"
	"github.com/lima-vm/lima/v2/pkg/limatype"
	"github.com/lima-vm/lima/v2/pkg/limatype/filenames"
	"github.com/lima-vm/lima/v2/pkg/textutil"
)

// startVM calls WSL to start a VM.
func startVM(ctx context.Context, distroName string) error {
	out, err := executil.RunUTF16leCommand([]string{
		"wsl.exe",
		"--distribution",
		distroName,
	}, executil.WithContext(ctx))
	if err != nil {
		return fmt.Errorf("failed to run `wsl.exe --distribution %s`: %w (out=%#q)",
			distroName, err, out)
	}
	return nil
}

// initVM calls WSL to import a new VM specifically for Lima.
func initVM(ctx context.Context, instanceDir, distroName string) error {
	baseDisk := filepath.Join(instanceDir, filenames.BaseDiskLegacy)
	logrus.Infof("Importing distro from %#q to %#q", baseDisk, instanceDir)
	out, err := executil.RunUTF16leCommand([]string{
		"wsl.exe",
		"--import",
		distroName,
		instanceDir,
		baseDisk,
	}, executil.WithContext(ctx))
	if err != nil {
		return fmt.Errorf("failed to run `wsl.exe --import %s %s %s`: %w (out=%#q)",

View on GitHub (pinned to dd909d0973)

Solutions

1. Run `wsl.exe --list --verbose` to confirm the distro exists and its state; re-import if missing (`limactl delete` + `limactl start` to recreate)
2. Read the out=... portion of the error — wsl.exe messages are UTF-16 decoded and state the actual reason
3. Run `wsl.exe --update` and ensure WSL2 (`wsl --set-default-version 2`) is properly installed
4. Reboot or `wsl.exe --shutdown` then retry if the WSL service is wedged
5. Check Windows optional features (Virtual Machine Platform, WSL) are enabled

Example fix

// debugging
// before: opaque failure
// after: inspect the embedded output
// if strings.Contains(out, "WSL_E_DISTRO_NOT_FOUND") {
//     // re-import the distro via limactl delete && limactl start
// }

out, err := exec.Command("wsl.exe", "--list", "--verbose").Output()
if err != nil || !strings.Contains(decodeUTF16(out), distroName) {
    return errors.New("distro not registered; run limactl start to import it")
}

func wslDistroExists(name string) bool {
    out, err := exec.Command("wsl.exe", "--list", "--quiet").Output()
    if err != nil { return false }
    return strings.Contains(decodeUTF16le(string(out)), name)
}

if err := driver.Start(ctx); err != nil {
    var msg string
    if strings.Contains(err.Error(), "wsl.exe --distribution") {
        msg = extractOutField(err.Error())
        // branch on WSL error code in msg, e.g. re-import distro
    }
    return fmt.Errorf("wsl start failed: %s", msg)
}

When it happens

Trigger: Start() -> startVM when wsl.exe returns a non-zero exit: distro not registered, WSL not installed/initialized, distro in a broken state, or WSL service issues.

Common situations: The Lima distro was never imported (initVM failed previously); `wsl --shutdown` left the distro stopped in a bad state; WSL2 kernel not installed; Windows features (VirtualMachinePlatform) disabled; low memory causing WSL VM start failure.

Related errors

• failed to run `wsl.exe --import %s %s %s`: %w (out=%#q)
• failed to run `wsl.exe --terminate %s`: %w (out=%#q)
• cannot use `--sync` with a wsl2 instance, the host directory
• unimplemented
• failed to construct wsl boot.sh script: %w

AI-assisted analysis of lima-vm/lima@dd909d0973 (2026-09-01). Data as JSON: /api/errors/82134490e0d544b3. Report an issue: GitHub.