lima-vm/lima · error

another hostagent may already be running with pid %d (pidfil

Error message

another hostagent may already be running with pid %d (pidfile %#q)

What it means

The hostagent startup detects that the PID file it was asked to write already contains a live PID, meaning another hostagent process may already be running for this instance. Starting a second hostagent would fight over the same instance, so hostagentAction aborts immediately after reading the pidfile.

Source

Thrown at cmd/limactl/hostagent.go:50

	}
	hostagentCommand.Flags().StringP("pidfile", "p", "", "Write PID to file")
	hostagentCommand.Flags().String("socket", "", "Path of hostagent socket")
	hostagentCommand.Flags().Bool("run-gui", false, "Run GUI synchronously within hostagent")
	hostagentCommand.Flags().String("guestagent", "", "Local file path (not URL) of lima-guestagent.OS-ARCH[.gz]")
	hostagentCommand.Flags().String("nerdctl-archive", "", "Local file path (not URL) of nerdctl-full-VERSION-GOOS-GOARCH.tar.gz")
	hostagentCommand.Flags().Bool("progress", false, "Show provision script progress by monitoring cloud-init logs")
	return hostagentCommand
}

func hostagentAction(cmd *cobra.Command, args []string) error {
	ctx := cmd.Context()
	pidfile, err := cmd.Flags().GetString("pidfile")
	if err != nil {
		return err
	}
	if pidfile != "" {
		if existingPID, err := store.ReadPIDFile(pidfile); existingPID != 0 {
			return fmt.Errorf("another hostagent may already be running with pid %d (pidfile %#q)", existingPID, pidfile)
		} else if err != nil {
			return fmt.Errorf("failed to determine if another hostagent is running: %w", err)
		}
		if err := store.WritePIDFile(pidfile, os.Getpid()); err != nil {
			return err
		}
		defer os.RemoveAll(pidfile)
	}
	socket, err := cmd.Flags().GetString("socket")
	if err != nil {
		return err
	}
	if socket == "" {
		return errors.New("socket must be specified (limactl version mismatch?)")
	}

	instName := args[0]

View on GitHub (pinned to dd909d0973)

Solutions

1. Check the PID in the pidfile (`cat <pidfile>; ps -p <pid>`) — if a hostagent is genuinely running, do not start another
2. Stop the existing instance with `limactl stop <instance>` before restarting
3. If the PID is dead but the file lingers, remove the stale pidfile and retry

Example fix

// before
limactl hostagent --pidfile ~/.lima/myinstance/hostagent.pid myinstance  # pidfile already held by live process
// after
limactl stop myinstance && limactl hostagent --pidfile ~/.lima/myinstance/hostagent.pid myinstance

if existingPID, err := store.ReadPIDFile(pidfile); existingPID != 0 {
    return fmt.Errorf("hostagent already running with pid %d", existingPID)
}

func hostagentAlreadyRunning(pidfile string) bool {
    pid, _ := store.ReadPIDFile(pidfile)
    return pid != 0
}

if err := startHostagent(); err != nil {
    if strings.Contains(err.Error(), "may already be running") { /* skip start or stop existing */ }
    return err
}

When it happens

Trigger: Running `limactl hostagent` (or an internal start path) with --pidfile pointing to a file where store.ReadPIDFile returns a non-zero PID that is still alive, i.e. a hostagent is already running for the instance.

Common situations: Double-starting an instance from two terminals; a stale-but-live PID file left after an aborted start; automation retried a start while the first start was still in progress.

Related errors

• failed to determine if another hostagent is running: %w
• invalid value for static parameter: %#q
• invalid parameter %#q, expected `static=` followed by a bool
• invalid parameter %#q, expected NAME=VALUE
• template does not define param %#q

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