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

Check the out= portion of the error for the specific wsl.exe message

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

Error message

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

What it means

During instance deletion, Lima runs `wsl.exe --unregister <distroName>` to remove the underlying WSL distro. If wsl.exe fails (non-zero exit), Lima wraps the error plus output; the distro may still exist on disk.

Source

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

	go func() {
		if err := keepAliveCmd.Run(); err != nil {
			errCh <- fmt.Errorf(
				"error running wsl keepAlive command: %w", err)
		}
	}()
}

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

// GetWslStatus runs `wsl --list --verbose` and parses its output.
// There are several possible outputs, all listed with their whitespace preserved output below.
//
// (1) Expected output if at least one distro is installed:
// PS > wsl --list --verbose
//
//	NAME      STATE           VERSION
//
// * Ubuntu    Stopped         2
//
// (2) Expected output when no distros are installed, but WSL is configured properly:
// PS > wsl --list --verbose
// Windows Subsystem for Linux has no installed distributions.

View on GitHub (pinned to dd909d0973)

Solutions

Check the out= portion of the error for the specific wsl.exe message
Run `wsl --list --verbose`; if the distro is Running, stop it (`wsl -t <distroName>`) then retry `limactl delete`
If the distro no longer exists, the instance is already gone from WSL — remove stale Lima metadata with `limactl delete --force`
Run `wsl --update` and retry if wsl.exe itself is misbehaving

Example fix

// before
limactl delete myinstance            // fails: distro still running
// after
wsl -t lima-myinstance
limactl delete myinstance            // succeeds

Defensive patterns

Strategy: try-catch

Validate before calling

// Check distro state before deleting
const list = execSync('wsl.exe --list --verbose').toString('utf16le');
const running = list.toLowerCase().includes('lima-' + inst) && /running/i.test(list);

Type guard

function isUnregisterError(e) { return String(e).includes('--unregister'); }

Try / catch

try {
  await limactlDelete(inst);
} catch (e) {
  if (String(e).includes('--unregister')) {
    try { execSync('wsl.exe -t lima-' + inst); } catch {}
    await limactlDelete(inst); // retry after stopping distro
  } else throw e;
}

Prevention

Stop the instance (`limactl stop`) before deleting
Check `wsl --list --verbose` before manual unregister operations
Use `limactl delete --force` only after confirming WSL state

When it happens

Trigger: `limactl delete` calls unregisterVM; wsl.exe --unregister exits non-zero — distro name not found, distro currently running/locked, or wsl.exe itself fails to launch.

Common situations: Deleting an instance whose distro was already removed manually; distro still running so unregister is rejected; WSL not properly installed; corrupted WSL registration.

Related errors

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