{"record":{"id":"6b1afc588ef5f994","repo":"lima-vm/lima","slug":"error-running-wsl-keepalive-command-w","errorCode":null,"errorMessage":"error running wsl keepAlive command: %w","messagePattern":"error running wsl keepAlive command: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/driver/wsl2/vm_windows.go","lineNumber":160,"sourceCode":"\n\treturn err\n}\n\n// keepAlive runs a background process which in order to keep the WSL2 VM running in the background after launch.\nfunc keepAlive(ctx context.Context, distroName string, errCh chan<- error) {\n\tkeepAliveCmd := exec.CommandContext(\n\t\tctx,\n\t\t\"wsl.exe\",\n\t\t\"-d\",\n\t\tdistroName,\n\t\t\"bash\",\n\t\t\"-c\",\n\t\t\"nohup sleep 2147483647d >/dev/null 2>&1\",\n\t)\n\n\tgo func() {\n\t\tif err := keepAliveCmd.Run(); err != nil {\n\t\t\terrCh <- fmt.Errorf(\n\t\t\t\t\"error running wsl keepAlive command: %w\", err)\n\t\t}\n\t}()\n}\n\n// unregisterVM calls WSL to unregister a VM.\nfunc unregisterVM(ctx context.Context, distroName string) error {\n\tlogrus.Info(\"Unregistering WSL2 VM\")\n\tout, err := executil.RunUTF16leCommand([]string{\n\t\t\"wsl.exe\",\n\t\t\"--unregister\",\n\t\tdistroName,\n\t}, executil.WithContext(ctx))\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to run `wsl.exe --unregister %s`: %w (out=%#q)\",\n\t\t\tdistroName, err, out)\n\t}\n\treturn nil","sourceCodeStart":142,"sourceCodeEnd":178,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/driver/wsl2/vm_windows.go#L142-L178","documentation":"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.","triggerScenarios":"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.","commonSituations":"User manually runs `wsl --unregister` or `wsl --shutdown` while an instance is running; WSL service restarts; distro is corrupted or removed externally.","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"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Ensure WSL is healthy before starting instances\nexecSync('wsl.exe --status');","typeGuard":"function isKeepAliveError(e) { return /wsl keepAlive command/.test(String(e)); }","tryCatchPattern":"try {\n  await limactlStart(inst);\n} catch (e) {\n  if (/keepAlive command/.test(String(e))) {\n    execSync('limactl stop ' + inst); // clean restart relaunches keepAlive\n    await limactlStart(inst);\n  } else throw e;\n}","preventionTips":["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"],"tags":["wsl2","process-lifecycle","keepalive"],"backgroundTag":"wsl-distro-terminated-unexpectedly","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}