lima-vm/lima · error

%s driver is running but host agent is not

Error message

%s driver is running but host agent is not

What it means

The mirror case of error 927: the driver (VM) process is alive but the host agent PID file is empty/gone. inspectStatusWithPIDFiles marks the instance Broken with '%s driver is running but host agent is not', naming the VM type (qemu, vz, ...).

Source

Thrown at pkg/store/instance.go:194

func inspectStatusWithPIDFiles(instDir string, inst *limatype.Instance, y *limatype.LimaYAML) {
	var err error
	inst.DriverPID, err = ReadPIDFile(filepath.Join(instDir, filenames.PIDFile(*y.VMType)))
	if err != nil {
		inst.Status = limatype.StatusBroken
		inst.Errors = append(inst.Errors, err)
	}

	if inst.Status == limatype.StatusUnknown {
		switch {
		case inst.HostAgentPID > 0 && inst.DriverPID > 0:
			inst.Status = limatype.StatusRunning
		case inst.HostAgentPID == 0 && inst.DriverPID == 0:
			inst.Status = limatype.StatusStopped
		case inst.HostAgentPID > 0 && inst.DriverPID == 0:
			inst.Errors = append(inst.Errors, errors.New("host agent is running but driver is not"))
			inst.Status = limatype.StatusBroken
		default:
			inst.Errors = append(inst.Errors, fmt.Errorf("%s driver is running but host agent is not", inst.VMType))
			inst.Status = limatype.StatusBroken
		}
	}
}

// ReadPIDFile returns 0 if the PID file does not exist, was written during a previous boot
// of the host, or the process has already terminated (in which case the PID file will be
// removed).
func ReadPIDFile(path string) (int, error) {
	// The boot is checked before the PID is read, so that a PID file of a previous boot is
	// never trusted, not even when another process refreshes the marker in between.
	if previousBoot, err := pidFileFromPreviousBoot(path); err != nil {
		return 0, err
	} else if previousBoot {
		// The PID was recorded before the last reboot, so it is meaningless now: it may
		// have been reused by an unrelated process, which must not be signaled. Removing
		// the file is left to WritePIDFile, which knows that no other process is writing
		// a PID file of the current boot into the same directory.

View on GitHub (pinned to dd909d0973)

Solutions

1. Find and kill the orphaned VM process (pgrep qemu-system / vz process) listed by the driver PID file
2. Remove leftover PID files and run `limactl start <inst>` to provision cleanly
3. Run `limactl delete -f <inst>` if the instance is no longer needed, to force-clean
4. Check hostagent stderr logs for the crash cause before restarting

Example fix

// before: qemu running, ha.pid gone -> Broken
// after
pkill -f 'qemu-system.*myvm'; limactl start myvm

haPid := store.ReadPIDFile(filepath.Join(instDir, "ha.pid"))
drvPid := store.ReadPIDFile(filepath.Join(instDir, "vm.pid"))
if drvPid > 0 && haPid == 0 {
    // orphaned VM: kill the driver process before restarting the instance
}

inst, err := store.Inspect(ctx, instDir)
if inst.Status == limatype.StatusBroken {
    for _, e := range inst.Errors {
        if strings.Contains(e.Error(), "driver is running but host agent is not") {
            // kill orphaned VM process by driver PID, then clean PID files and start
        }
    }
}

When it happens

Trigger: HostAgentPID == 0 && DriverPID > 0: ha.pid missing/emptied while the VM driver process still runs — hostagent crashed, PID file deleted, or instance dir partially cleaned while the VM keeps running.

Common situations: User deleted files under ~/.lima/<inst> while the VM ran; hostagent crashed after provisioning; concurrent limactl commands raced and removed PID files; kill of hostagent during shutdown left the VM orphaned.

Related errors

• host agent is running but driver is not
• failed to inspect status: %w
• invalid value for static parameter: %#q
• invalid parameter %#q, expected `static=` followed by a bool
• invalid parameter %#q, expected NAME=VALUE

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