{"record":{"id":"3ae171825916881b","repo":"lima-vm/lima","slug":"host-agent-process-has-exited-w","errorCode":null,"errorMessage":"host agent process has exited: %w","messagePattern":"host agent process has exited: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"pkg/instance/start.go","lineNumber":342,"sourceCode":"\t}()\n\twaitErrCh := make(chan error)\n\tif haCmd != nil {\n\t\tgo func() {\n\t\t\twaitErrCh <- haCmd.Wait()\n\t\t\tclose(waitErrCh)\n\t\t}()\n\t} else {\n\t\tdefer close(waitErrCh)\n\t}\n\n\tselect {\n\tcase watchErr := <-watchErrCh:\n\t\t// watchErr can be nil\n\t\treturn watchErr\n\t\t// leave the hostagent process running\n\tcase waitErr := <-waitErrCh:\n\t\t// waitErr should not be nil\n\t\treturn fmt.Errorf(\"host agent process has exited: %w\", waitErr)\n\t}\n}\n\nfunc Start(ctx context.Context, inst *limatype.Instance, launchHostAgentForeground, showProgress bool) error {\n\treturn StartWithPaths(ctx, inst, launchHostAgentForeground, showProgress, \"\", \"\")\n}\n\nfunc waitHostAgentStart(_ context.Context, haPIDPath, haStderrPath string) error {\n\tbegin := time.Now()\n\tdeadlineDuration := 5 * time.Second\n\tdeadline := begin.Add(deadlineDuration)\n\tfor {\n\t\tif _, err := os.Stat(haPIDPath); !errors.Is(err, os.ErrNotExist) {\n\t\t\treturn nil\n\t\t}\n\t\tif time.Now().After(deadline) {\n\t\t\treturn fmt.Errorf(\"hostagent (%#q) did not start up in %v (hint: see %#q)\", haPIDPath, deadlineDuration, haStderrPath)\n\t\t}","sourceCodeStart":324,"sourceCodeEnd":360,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/instance/start.go#L324-L360","documentation":"lima wraps the hostagent process wait error when the hostagent process terminates while limactl is still watching it. In StartWithPaths, two channels race: watchErrCh (event watching result) and waitErrCh (process exit). If waitErrCh fires first, the hostagent process exited prematurely, and the underlying wait error is wrapped with %w so root causes (signal, exec failure) are preserved.","triggerScenarios":"Running `limactl start` when the hostagent binary crashes or is killed before it finishes setting up; the waitHostAgent goroutine returns a non-nil waitErr that wins the select over watchErrCh.","commonSituations":"Hostagent panics on malformed lima.yaml, missing dependencies on the host, OOM-kill of the hostagent process, or incompatible lima version after upgrade leaving stale state in ~/.lima/<instance>.","solutions":["Inspect the hostagent log at ~/.lima/<instance>/ha.stderr.log for the actual crash cause","Validate lima.yaml with `limactl start --print` or `limactl validate` before starting","Remove stale instance state with `limactl delete -f <instance>` and recreate","Upgrade/reinstall lima so the hostagent binary matches limactl version"],"exampleFix":"// before\nerr := lima.Start(ctx, inst) // opaque: host agent process has exited: exit status 2\n// after\nif err != nil {\n    logrus.Debugf(\"ha.stderr: %s\", readHAStderr(inst))\n    return fmt.Errorf(\"start failed: %w\", err)\n}","handlingStrategy":"try-catch","validationCode":"// before start\nif _, err := os.Stat(filepath.Join(home, \".lima\", instName, \"lima.yaml\")); err != nil { recreate() }\nout, err := exec.Command(\"limactl\", \"validate\", cfgPath).CombinedOutput()\nif err != nil { log.Fatalf(\"invalid config: %s\", out) }","typeGuard":"var waitErr interface{ Unwrap() error }\nif errors.As(err, &target) { /* inspect wrapped exec.ExitError */ }\nvar ee *exec.ExitError\nif errors.As(err, &ee) { code := ee.ExitCode() }","tryCatchPattern":"err := lima.Start(ctx, inst)\nif err != nil && strings.Contains(err.Error(), \"host agent process has exited\") {\n    log := filepath.Join(home, \".lima\", inst.Name, \"ha.stderr.log\")\n    b, _ := os.ReadFile(log)\n    return fmt.Errorf(\"hostagent crashed: %w\\nha.stderr:\\n%s\", err, b)\n}","preventionTips":["Validate lima.yaml before every start","Keep limactl and guestagent binaries from the same release","Watch ha.stderr.log on failure","Avoid killing processes named lima/hostagent during startup"],"tags":["process","hostagent","vm-startup"],"backgroundTag":"hostagent-process-exited","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}