What causes "failed to run `wsl.exe --terminate %s`: %w (out=%#q)" in lima-vm/lima?

Check `wsl.exe --list --verbose` for the distro's actual registered name and state

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

Error message

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

What it means

stopVM runs `wsl.exe --terminate <distroName>` to stop the Lima WSL distro. If wsl.exe exits non-zero, the driver wraps the error and decoded output. This means WSL refused to terminate the distribution (or the command itself failed).

Source

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

		instanceDir,
		baseDisk,
	}, executil.WithContext(ctx))
	if err != nil {
		return fmt.Errorf("failed to run `wsl.exe --import %s %s %s`: %w (out=%#q)",
			distroName, instanceDir, baseDisk, err, out)
	}
	return nil
}

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

//go:embed lima-init.TEMPLATE
var limaBoot string

// provisionVM starts Lima's boot process inside an already imported VM.
func provisionVM(ctx context.Context, instanceDir, instanceName, distroName string, errCh chan<- error) error {
	ciDataPath := filepath.Join(instanceDir, filenames.CIDataISODir)
	m := map[string]string{
		"CIDataPath": ciDataPath,
	}
	limaBootB, err := textutil.ExecuteTemplate(limaBoot, m)
	if err != nil {
		return fmt.Errorf("failed to construct wsl boot.sh script: %w", err)
	}

View on GitHub (pinned to dd909d0973)

Solutions

Check `wsl.exe --list --verbose` for the distro's actual registered name and state
If the distro is already Stopped, treat the error as harmless and continue (idempotent stop)
Run `wsl.exe --shutdown` to reset the WSL VM if terminate keeps failing, then retry
Read the out= field for the wsl.exe error code (e.g. not-found) and act accordingly
Restart the LxssManager/WSL service or reboot if the WSL service is unresponsive

Example fix

// before
err := driver.Stop(ctx) // terminate failed
// after
if err := driver.Stop(ctx); err != nil {
    if !strings.Contains(err.Error(), "not found") {
        return err // only real failures
    } // already stopped: ignore
}

Defensive patterns

Strategy: fallback

Validate before calling

// confirm distro is running before terminating
out, _ := exec.Command("wsl.exe", "--list", "--verbose").Output()
if !strings.Contains(decodeUTF16le(string(out)), "Running") {
    return nil // already stopped; skip terminate
}

Try / catch

if err := driver.Stop(ctx); err != nil {
    if strings.Contains(err.Error(), "--terminate") {
        // fallback: reset WSL entirely
        exec.Command("wsl.exe", "--shutdown").Run()
    }
    return err
}

Prevention

Avoid double-stop of the same instance concurrently
Don't delete an instance while it's stopping
Keep wsl.exe on PATH for the process environment
Reset WSL after host sleep/resume if terminate fails repeatedly

When it happens

Trigger: Stop() (or an anonymous caller) invokes stopVM and wsl.exe --terminate returns non-zero: distro not registered, name mismatch, or WSL service failure.

Common situations: Distro already gone (double-stop, instance deleted concurrently); WSL service wedged after host sleep; distro name drifted from what WSL has registered; wsl.exe unavailable in PATH for the calling process.

Related errors

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