lima-vm/lima · error

instance %#q seems running (hint: remove %#q if the instance

Error message

instance %#q seems running (hint: remove %#q if the instance is not actually running)

What it means

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).

Source

Thrown at pkg/instance/start.go:231

// shut down again.
//
// The showProgress argument tells the hostagent to show provision script progress by tailing cloud-init logs.
//
// The limactl argument allows the caller to specify the full path of the limactl executable.
// The guestAgent argument allows the caller to specify the full path of the guest agent executable.
// Inside limactl this function is only called by Start, which passes empty strings for both
// limactl and guestAgent, in which case the location of the current executable is used for
// limactl and the guest agent is located from the corresponding <prefix>/share/lima directory.
//
// StartWithPaths calls Prepare by itself, so you do not need to call Prepare manually before calling Start.
func StartWithPaths(ctx context.Context, inst *limatype.Instance, launchHostAgentForeground, showProgress bool, limactl, guestAgent string) error {
	haPIDPath := filepath.Join(inst.Dir, filenames.HostAgentPID)
	// ReadPIDFile removes the PID file when it was left behind by a process that is not
	// running anymore, or by a previous boot of the host.
	if haPID, err := store.ReadPIDFile(haPIDPath); err != nil {
		return err
	} else if haPID != 0 {
		return fmt.Errorf("instance %#q seems running (hint: remove %#q if the instance is not actually running)", inst.Name, haPIDPath)
	}
	logrus.Infof("Starting the instance %#q with %s VM driver %#q", inst.Name, registry.CheckInternalOrExternal(inst.VMType), inst.VMType)

	haSockPath := filepath.Join(inst.Dir, filenames.HostAgentSock)

	prepared, err := Prepare(ctx, inst, guestAgent)
	if err != nil {
		return err
	}

	if limactl == "" {
		limactl, err = os.Executable()
		if err != nil {
			return err
		}
	}
	haStdoutPath := filepath.Join(inst.Dir, filenames.HostAgentStdoutLog)
	haStderrPath := filepath.Join(inst.Dir, filenames.HostAgentStderrLog)

View on GitHub (pinned to dd909d0973)

Solutions

1. Check `limactl list <inst>` - if the instance is running, do not start it again.
2. 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.
3. Verify the PID in ~/.lima/<inst>/ha.pid: ps -p $(cat .../ha.pid) to see what it actually is.
4. After a crash, run `limactl factory-reset` or delete the instance to clear state.

Example fix

// before
limactl start myvm  # error: seems running
// after
limactl list myvm          # confirm state
ps -p $(cat ~/.lima/myvm/ha.pid)  # verify PID
limactl stop -f myvm && limactl start myvm  # if stale

// before starting, check instance state
inst, _ := store.Inspect(ctx, instName)
if inst.Status == limatype.StatusRunning {
  return fmt.Errorf("instance %s already running", instName)
}
haPIDPath := filepath.Join(inst.Dir, "ha.pid")
if pid, _ := store.ReadPIDFile(haPIDPath); pid != 0 {
  return fmt.Errorf("host agent alive (pid %d)", pid)
}

func instanceStopped(inst *limatype.Instance) bool {
  return inst.Status == "Stopped" || inst.Status == "Broken"
}

err := instance.Start(ctx, inst, "")
if err != nil && strings.Contains(err.Error(), "seems running") {
  // verify and clear stale PID file, then retry once
  if pid, _ := os.ReadFile(filepath.Join(inst.Dir, "ha.pid")); !processAlive(pid) {
    os.Remove(filepath.Join(inst.Dir, "ha.pid"))
    err = instance.Start(ctx, inst, "")
  }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• failed to write driver PID file: %w
• external driver process exited before creating socket file
• external driver process exited before creating socket file:
• timed out waiting for external driver to create socket file
• vz driver requires macOS 13 or higher to run: %w

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