failed to read instance state for instance %#q, try running

Error message

failed to read instance state for instance %#q, try running `wsl --list --verbose` to debug, err: %w

What it means

After `wsl --list --verbose` succeeds, if its output is empty Lima cannot determine the instance state and reports the instance as StatusBroken. This also happens when err was non-nil but out was empty, so the wrapped err is often a nil-interface artifact.

Source

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

// (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)
	}

	var instState string
	wslListColsRegex := regexp.MustCompile(`\s+`)
	// wsl --list --verbose may have different headers depending on localization, just split by line

View on GitHub (pinned to dd909d0973)

Solutions

Run `wsl --list --verbose` manually to confirm output
If no distros exist, install one (`wsl --install -d Ubuntu`) and re-run Lima
Update WSL (`wsl --update`) to get consistent UTF-16le output
Recreate the instance with `limactl start` once WSL lists correctly

Defensive patterns

Strategy: fallback

Validate before calling

// Ensure at least one distro exists and listing is non-empty
const out = execSync('wsl.exe --list --verbose').toString('utf16le').trim();
if (!out) throw new Error('wsl --list --verbose returned nothing; reinstall WSL');

Type guard

function isBrokenStateQuery(e) { return /failed to read instance state/.test(String(e)); }

Try / catch

try {
  const st = await limactlInspect(inst);
} catch (e) {
  if (/failed to read instance state/.test(String(e))) {
    // treat instance as broken; offer recreate path
    console.warn('Instance state unreadable; run limactl delete and start fresh');
  } else throw e;
}

Prevention

Never leave a Windows user profile with zero WSL distros
Update WSL so `--list --verbose` always emits parseable UTF-16le output
After WSL reinstall, recreate Lima instances rather than reusing broken state

When it happens

Trigger: getWslStatus receives out == "" from a successful (or vacuously failing) `wsl --list --verbose` run — no distro listing could be parsed.

Common situations: WSL installed but no distributions registered; wsl.exe emitting only a warning line; WSL in a partially installed state producing no listing; older WSL versions with different output encodings.

Related errors

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