lima-vm/lima · error

failed to run `wsl --list --verbose`, err: %w (out=%#q)

Error message

failed to run `wsl --list --verbose`, err: %w (out=%#q)

What it means

To determine instance state, the driver runs `wsl.exe --list --verbose` (UTF-16le output) and parses it. Any failure of that command is wrapped with the raw output so the user can debug WSL directly; no state string is produced.

Source

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

// Distributions can also be installed by visiting the Microsoft Store:
// https://aka.ms/wslstore
// Error code: Wsl/WSL_E_DEFAULT_DISTRO_NOT_FOUND
//
// (3) Expected output when no distros are installed, and WSL2 has no kernel installed:
//
// PS > wsl --list --verbose
// Windows Subsystem for Linux has no installed distributions.
// Distributions can be installed by visiting the Microsoft Store:
// https://aka.ms/wslstore
func getWslStatus(ctx context.Context, instName string) (string, error) {
	distroName := "lima-" + instName
	out, err := executil.RunUTF16leCommand([]string{
		"wsl.exe",
		"--list",
		"--verbose",
	}, executil.WithContext(ctx))
	if err != nil {
		return "", fmt.Errorf("failed to run `wsl --list --verbose`, err: %w (out=%#q)", err, out)
	}

	if out == "" {
		return limatype.StatusBroken, fmt.Errorf("failed to read instance state for instance %#q, try running `wsl --list --verbose` to debug, err: %w", instName, err)
	}

	// Check for edge cases first
	if strings.Contains(out, "Windows Subsystem for Linux has no installed distributions.") {
		if strings.Contains(out, "Wsl/WSL_E_DEFAULT_DISTRO_NOT_FOUND") {
			return limatype.StatusBroken, fmt.Errorf(
				"failed to read instance state for instance %#q because no distro is installed,"+
					"try running `wsl --install -d Ubuntu` and then re-running Lima", instName)
		}
		return limatype.StatusBroken, fmt.Errorf(
			"failed to read instance state for instance %#q because there is no WSL kernel installed,"+
				"this usually happens when WSL was installed for another user, but never for your user."+
				"Try running `wsl --install -d Ubuntu` and `wsl --update`, and then re-running Lima", instName)
	}

View on GitHub (pinned to dd909d0973)

Solutions

1. Run `wsl --list --verbose` manually in PowerShell to reproduce and see the real error
2. Install/enable WSL: `wsl --install` and reboot
3. Update WSL with `wsl --update`
4. Retry the limactl command after WSL responds correctly

// Preflight: confirm wsl.exe works before Lima operations
execSync('wsl.exe --list --verbose', { stdio: 'inherit' });

function isWslListError(e) { return String(e).includes('--list --verbose'); }

try {
  await limactlStart(inst);
} catch (e) {
  if (String(e).includes('--list --verbose')) {
    throw new Error('WSL CLI unavailable; run `wsl --install` / `wsl --update` first. Original: ' + e.message);
  } else throw e;
}

When it happens

Trigger: getWslStatus (via InspectStatus, Delete, Start) invokes `wsl.exe --list --verbose` and it exits non-zero — WSL not installed, wsl.exe path issues, or WSL service errors.

Common situations: WSL feature not enabled on Windows, wsl.exe outdated or corrupted, running in a context where wsl.exe is unavailable, WSL first-run not completed.

Related errors

• failed to read instance state for instance %#q, try running
• 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/fd5f1e311b4048d6. Report an issue: GitHub.