lima-vm/lima · error

failed to run wslpath command: %w

Error message

failed to run wslpath command: %w

What it means

provisionVM runs a wslpath command to convert the Windows temp boot-script path into its Linux-side path inside the WSL distro. On failure it removes the temp file and returns this wrapped error (explicitly wrapped so handleExitCoder doesn't swallow exit-code errors). It means the boot script path could not be translated, so provisioning cannot proceed.

Source

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

		return err
	}
	// path should be quoted and use \\ as separator
	bootFileWSLPath := strconv.Quote(limaBootFileWinPath)
	limaBootFilePathOnLinuxB, err := exec.CommandContext(
		ctx,
		"wsl.exe",
		"-d",
		distroName,
		"bash",
		"-c",
		fmt.Sprintf("wslpath -u %s", bootFileWSLPath),
		bootFileWSLPath,
	).Output()
	if err != nil {
		os.RemoveAll(limaBootFileWinPath)
		// this can return an error with an exit code, which causes it not to be logged
		// because main.handleExitCoder() traps it, so wrap the error
		return fmt.Errorf("failed to run wslpath command: %w", err)
	}
	limaBootFileLinuxPath := strings.TrimSpace(string(limaBootFilePathOnLinuxB))
	go func() {
		cmd := exec.CommandContext(
			ctx,
			"wsl.exe",
			"-d",
			distroName,
			"bash",
			"-c",
			limaBootFileLinuxPath,
		)
		out, err := cmd.CombinedOutput()
		os.RemoveAll(limaBootFileWinPath)
		logrus.Debugf("%v: %#q", cmd.Args, string(out))
		if err != nil {
			errCh <- fmt.Errorf(
				"error running wslCommand that executes boot.sh (%v): %w, "+

View on GitHub (pinned to dd909d0973)

Solutions

1. Ensure the distro is running and healthy: `wsl.exe --distribution <name> -- true`; restart if not
2. Check WSL interop is enabled in .wslconfig (interop enabled) so Windows->Linux command execution works
3. Read the wrapped err for the exit code; run the wslpath conversion manually to reproduce
4. Recreate the distro (`limactl delete` + `limactl start`) if the guest init is broken
5. Update WSL (`wsl.exe --update`) — interop/wslpath issues are fixed in newer releases

Example fix

// before (silent exit-code swallow in callers)
// after (driver wraps it): inspect and retry
if err := driver.Start(ctx); err != nil {
    if strings.Contains(err.Error(), "wslpath") {
        exec.Command("wsl.exe", "--shutdown").Run() // reset WSL then retry
    }
}

// verify the distro is bootable and interop works before provisioning
if err := exec.Command("wsl.exe", "-d", distroName, "--", "/usr/bin/wslpath", "C:\\").Run(); err != nil {
    return errors.New("wsl interop/wslpath unavailable; check distro health and .wslconfig interop settings")
}

if err := driver.Start(ctx); err != nil {
    if strings.Contains(err.Error(), "wslpath") {
        exec.Command("wsl.exe", "--shutdown").Run()
        time.Sleep(2 * time.Second)
        return driver.Start(ctx) // one reset-and-retry
    }
    return err
}

When it happens

Trigger: Start() -> provisionVM when the wslpath command exits non-zero: the WSL distro is not running, wsl.exe invocation fails, or the distro lacks /usr/bin/wslpath (non-standard/failed init).

Common situations: Distro failed to fully boot so wslpath (part of WSL's init/interop) is unavailable; WSL interop disabled (appendWindowsPath/interop settings); path with characters wslpath mishandles; WSL service wedged.

Related errors

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

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