What causes "error running wsl keepAlive command: %w" in lima-vm/lima?

Check whether the distro still exists with `wsl --list --verbose`; re-register or recreate if unregistered

error running wsl keepAlive command: %w

Error message

error running wsl keepAlive command: %w

What it means

The WSL2 driver keeps the distro alive by launching a long-running `sleep 2147483647d` process via wsl.exe; without it WSL would tear the distro down when no process runs. If that keepAlive command exits non-zero, the goroutine reports it on errCh.

Source

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

	return err
}

// keepAlive runs a background process which in order to keep the WSL2 VM running in the background after launch.
func keepAlive(ctx context.Context, distroName string, errCh chan<- error) {
	keepAliveCmd := exec.CommandContext(
		ctx,
		"wsl.exe",
		"-d",
		distroName,
		"bash",
		"-c",
		"nohup sleep 2147483647d >/dev/null 2>&1",
	)

	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

View on GitHub (pinned to dd909d0973)

Solutions

Check whether the distro still exists with `wsl --list --verbose`; re-register or recreate if unregistered
Avoid running `wsl --shutdown` or `wsl --unregister` while Lima instances are running; use `limactl stop/delete` instead
Restart the instance with `limactl start` to relaunch the keepAlive process
Update WSL (`wsl --update`) if the distro crashes repeatedly

Defensive patterns

Strategy: try-catch

Validate before calling

// Ensure WSL is healthy before starting instances
execSync('wsl.exe --status');

Type guard

function isKeepAliveError(e) { return /wsl keepAlive command/.test(String(e)); }

Try / catch

try {
  await limactlStart(inst);
} catch (e) {
  if (/keepAlive command/.test(String(e))) {
    execSync('limactl stop ' + inst); // clean restart relaunches keepAlive
    await limactlStart(inst);
  } else throw e;
}

Prevention

Never run `wsl --shutdown` or `wsl --unregister` while Lima instances are running
Use `limactl stop`/`limactl delete` instead of manipulating WSL directly
Keep WSL updated (`wsl --update`) to avoid distro crashes

When it happens

Trigger: The `wsl.exe -d <distro> -u root -- nohup sleep 2147483647d` command returns an error in its background goroutine, e.g. the distro was unregistered or WSL shut down while Lima still considers the instance running.

Common situations: User manually runs `wsl --unregister` or `wsl --shutdown` while an instance is running; WSL service restarts; distro is corrupted or removed externally.

Related errors

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