{"record":{"id":"695d023554a77ab9","repo":"lima-vm/lima","slug":"instance-q-seems-running-hint-remove-q-if-th","errorCode":null,"errorMessage":"instance %#q seems running (hint: remove %#q if the instance is not actually running)","messagePattern":"instance %#q seems running \\(hint: remove %#q if the instance is not actually running\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/instance/start.go","lineNumber":231,"sourceCode":"// shut down again.\n//\n// The showProgress argument tells the hostagent to show provision script progress by tailing cloud-init logs.\n//\n// The limactl argument allows the caller to specify the full path of the limactl executable.\n// The guestAgent argument allows the caller to specify the full path of the guest agent executable.\n// Inside limactl this function is only called by Start, which passes empty strings for both\n// limactl and guestAgent, in which case the location of the current executable is used for\n// limactl and the guest agent is located from the corresponding <prefix>/share/lima directory.\n//\n// StartWithPaths calls Prepare by itself, so you do not need to call Prepare manually before calling Start.\nfunc StartWithPaths(ctx context.Context, inst *limatype.Instance, launchHostAgentForeground, showProgress bool, limactl, guestAgent string) error {\n\thaPIDPath := filepath.Join(inst.Dir, filenames.HostAgentPID)\n\t// ReadPIDFile removes the PID file when it was left behind by a process that is not\n\t// running anymore, or by a previous boot of the host.\n\tif haPID, err := store.ReadPIDFile(haPIDPath); err != nil {\n\t\treturn err\n\t} else if haPID != 0 {\n\t\treturn fmt.Errorf(\"instance %#q seems running (hint: remove %#q if the instance is not actually running)\", inst.Name, haPIDPath)\n\t}\n\tlogrus.Infof(\"Starting the instance %#q with %s VM driver %#q\", inst.Name, registry.CheckInternalOrExternal(inst.VMType), inst.VMType)\n\n\thaSockPath := filepath.Join(inst.Dir, filenames.HostAgentSock)\n\n\tprepared, err := Prepare(ctx, inst, guestAgent)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tif limactl == \"\" {\n\t\tlimactl, err = os.Executable()\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t}\n\thaStdoutPath := filepath.Join(inst.Dir, filenames.HostAgentStdoutLog)\n\thaStderrPath := filepath.Join(inst.Dir, filenames.HostAgentStderrLog)","sourceCodeStart":213,"sourceCodeEnd":249,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/instance/start.go#L213-L249","documentation":"Before starting the host agent, StartWithPaths reads the host agent PID file. If store.ReadPIDFile returns a live PID, the instance is considered already running and start is refused, with a hint that a stale PID file can be removed if no process is actually running (ReadPIDFile normally cleans up dead-PID files, so a live PID usually means a real running instance).","triggerScenarios":"Running `limactl start <inst>` while the instance is already started; a PID file at ~/.lima/<inst>/ha.pid whose PID belongs to a live, unrelated process (PID reuse) or a leftover host agent.","commonSituations":"Double-invoking start in scripts; a host agent that was SIGKILLed in a way that left state inconsistent; PID reuse after a crash making Lima think the old agent is alive.","solutions":["Check `limactl list <inst>` - if the instance is running, do not start it again.","If no lima processes exist (ps aux | grep lima), the PID was reused/left stale: remove the ha.pid file or run `limactl stop -f <inst>` / `limactl delete <inst>` as the hint suggests.","Verify the PID in ~/.lima/<inst>/ha.pid: ps -p $(cat .../ha.pid) to see what it actually is.","After a crash, run `limactl factory-reset` or delete the instance to clear state."],"exampleFix":"// before\nlimactl start myvm  # error: seems running\n// after\nlimactl list myvm          # confirm state\nps -p $(cat ~/.lima/myvm/ha.pid)  # verify PID\nlimactl stop -f myvm && limactl start myvm  # if stale","handlingStrategy":"validation","validationCode":"// before starting, check instance state\ninst, _ := store.Inspect(ctx, instName)\nif inst.Status == limatype.StatusRunning {\n  return fmt.Errorf(\"instance %s already running\", instName)\n}\nhaPIDPath := filepath.Join(inst.Dir, \"ha.pid\")\nif pid, _ := store.ReadPIDFile(haPIDPath); pid != 0 {\n  return fmt.Errorf(\"host agent alive (pid %d)\", pid)\n}","typeGuard":"func instanceStopped(inst *limatype.Instance) bool {\n  return inst.Status == \"Stopped\" || inst.Status == \"Broken\"\n}","tryCatchPattern":"err := instance.Start(ctx, inst, \"\")\nif err != nil && strings.Contains(err.Error(), \"seems running\") {\n  // verify and clear stale PID file, then retry once\n  if pid, _ := os.ReadFile(filepath.Join(inst.Dir, \"ha.pid\")); !processAlive(pid) {\n    os.Remove(filepath.Join(inst.Dir, \"ha.pid\"))\n    err = instance.Start(ctx, inst, \"\")\n  }\n}","preventionTips":["Gate start calls on `limactl list` state","Never invoke start twice in scripts; make it idempotent","After SIGKILL/crash, run stop -f or factory-reset to clear state","Check the PID in ha.pid actually belongs to a lima process before removing it"],"tags":["pid-file","already-running","startup"],"backgroundTag":"instance-already-running","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}