{"record":{"id":"c1644c47b9725a04","repo":"lima-vm/lima","slug":"hostagent-q-did-not-start-up-in-v-hint-see","errorCode":null,"errorMessage":"hostagent (%#q) did not start up in %v (hint: see %#q)","messagePattern":"hostagent \\(%#q\\) did not start up in (.+?) \\(hint: see %#q\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/instance/start.go","lineNumber":359,"sourceCode":"\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}\n\t}\n}\n\nfunc watchHostAgentEvents(ctx context.Context, inst *limatype.Instance, haStdoutPath, haStderrPath string, begin time.Time, showProgress bool) error {\n\tctx, cancel := context.WithTimeout(ctx, watchHostAgentTimeout(ctx))\n\tdefer cancel()\n\n\tvar (\n\t\tprintedSSHLocalPort  bool\n\t\treceivedRunningEvent bool\n\t\tcloudInitCompleted   bool\n\t\terr                  error\n\t)\n\n\tonEvent := func(ev hostagentevents.Event) bool {\n\t\tif !printedSSHLocalPort && ev.Status.SSHLocalPort != 0 {\n\t\t\tlogrus.Infof(\"SSH Local Port: %d\", ev.Status.SSHLocalPort)","sourceCodeStart":341,"sourceCodeEnd":377,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/instance/start.go#L341-L377","documentation":"waitHostAgentStart polls for the hostagent PID file (haPIDPath) and throws if it does not appear within deadlineDuration. The PID file is written by the hostagent shortly after launch; absence means the hostagent never got far enough to register itself. The error points the user at the PID path and the ha.stderr.log path for diagnosis.","triggerScenarios":"Calling `limactl start` (which invokes StartWithPaths -> waitHostAgentStart) when the hostagent fails to launch at all: binary not found, exec permission error, or immediate crash before writing the PID file.","commonSituations":"Stale/locked ~/.lima directory, limactl binary moved after install, antivirus blocking the process, or extremely slow disk making startup exceed the deadline.","solutions":["Read the referenced ha.stderr.log file for the launch failure","Check the hostagent binary path exists and is executable (`ls -l ~/.lima/bin/limactl` or install dir)","Retry after system slowness subsides; check disk/CPU pressure","Reinstall lima to restore a consistent binary layout"],"exampleFix":"// diagnosis snippet\nif strings.Contains(err.Error(), \"did not start up in\") {\n    fmt.Println(\"see:\", filepath.Join(inst.Dir, \"ha.stderr.log\"))\n}","handlingStrategy":"try-catch","validationCode":"haPID := filepath.Join(instDir, \"ha.pid\")\nif _, err := os.Stat(haPID); err == nil { /* hostagent already up or stale */ }","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"did not start up in\") {\n    b, _ := os.ReadFile(filepath.Join(instDir, \"ha.stderr.log\"))\n    return fmt.Errorf(\"hostagent never registered: %w\\n%s\", err, b)\n}","preventionTips":["Ensure no stale ha.pid file before starting","Run on a machine with adequate disk/CPU so startup beats the deadline","Keep antivirus from blocking limactl/lima binaries","Use matching limactl/hostagent versions"],"tags":["hostagent","timeout","pidfile"],"backgroundTag":"process-startup-timeout","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}