lima-vm/lima · error

failed to determine if another hostagent is running

Error message

failed to determine if another hostagent is running: %w

What it means

Before writing its own PID, the hostagent calls store.ReadPIDFile to check for an existing runner; if that read fails for any reason (unreadable file, permission error, malformed contents) the command cannot know whether another hostagent is running and fails closed with this wrapped error.

Solutions

1. Inspect the pidfile: `ls -la <pidfile>` and `cat <pidfile>`; fix permissions or delete the corrupted file
2. Ensure the LIMA_HOME instance directory is writable by the current user
3. Retry the start after removing the malformed pidfile

Example fix

// before
# pidfile unreadable (root-owned after sudo run)
// after
sudo chown -R $(whoami) ~/.lima/myinstance && limactl start myinstance

if fi, err := os.Stat(pidfile); err == nil && !fi.Mode().IsRegular() {
    return fmt.Errorf("pidfile %s is not a regular file", pidfile)
}

func pidfileReadable(pidfile string) bool {
    f, err := os.Open(pidfile)
    if err != nil { return false }
    f.Close()
    return true
}

if err := startHostagent(); err != nil {
    var wrapped string = err.Error()
    if strings.Contains(wrapped, "failed to determine if another hostagent") {
        os.Remove(pidfile) // clear corrupted pidfile, then retry
    }
    return err
}

When it happens

Trigger: Calling hostagent with --pidfile where store.ReadPIDFile returns an error and a zero PID — e.g. pidfile exists but is not readable, is a directory, or contains garbage that cannot be parsed as a PID.

Common situations: LIMA_HOME on a mounted volume with wrong permissions; a corrupted pidfile after a crash or disk-full event; pidfile path pointing at a directory instead of a file.

Related errors

• another hostagent may already be running with pid
• pidfile %#q already exists
• failed to determine the host directory to sync
• failed to unprotect instance %#q
• field `mounts[ ].location` refers to a non-directory path…

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

Appendix: source

Thrown at cmd/limactl/hostagent.go:52

	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]

	runGUI, err := cmd.Flags().GetBool("run-gui")
	if err != nil {

View on GitHub (pinned to dd909d0973)