lima-vm/lima · error

hostagent (%#q) did not start up in %v (hint: see %#q)

Error message

hostagent (%#q) did not start up in %v (hint: see %#q)

What it means

waitHostAgentStart polls for the hostagent PID file (haPIDPath) and throws if it does not appear within deadlineDuration. The PID file is written by the hostagent shortly after launch; absence means the hostagent never got far enough to register itself. The error points the user at the PID path and the ha.stderr.log path for diagnosis.

Source

Thrown at pkg/instance/start.go:359

		// waitErr should not be nil
		return fmt.Errorf("host agent process has exited: %w", waitErr)
	}
}

func Start(ctx context.Context, inst *limatype.Instance, launchHostAgentForeground, showProgress bool) error {
	return StartWithPaths(ctx, inst, launchHostAgentForeground, showProgress, "", "")
}

func waitHostAgentStart(_ context.Context, haPIDPath, haStderrPath string) error {
	begin := time.Now()
	deadlineDuration := 5 * time.Second
	deadline := begin.Add(deadlineDuration)
	for {
		if _, err := os.Stat(haPIDPath); !errors.Is(err, os.ErrNotExist) {
			return nil
		}
		if time.Now().After(deadline) {
			return fmt.Errorf("hostagent (%#q) did not start up in %v (hint: see %#q)", haPIDPath, deadlineDuration, haStderrPath)
		}
	}
}

func watchHostAgentEvents(ctx context.Context, inst *limatype.Instance, haStdoutPath, haStderrPath string, begin time.Time, showProgress bool) error {
	ctx, cancel := context.WithTimeout(ctx, watchHostAgentTimeout(ctx))
	defer cancel()

	var (
		printedSSHLocalPort  bool
		receivedRunningEvent bool
		cloudInitCompleted   bool
		err                  error
	)

	onEvent := func(ev hostagentevents.Event) bool {
		if !printedSSHLocalPort && ev.Status.SSHLocalPort != 0 {
			logrus.Infof("SSH Local Port: %d", ev.Status.SSHLocalPort)

View on GitHub (pinned to dd909d0973)

Solutions

1. Read the referenced ha.stderr.log file for the launch failure
2. Check the hostagent binary path exists and is executable (`ls -l ~/.lima/bin/limactl` or install dir)
3. Retry after system slowness subsides; check disk/CPU pressure
4. Reinstall lima to restore a consistent binary layout

Example fix

// diagnosis snippet
if strings.Contains(err.Error(), "did not start up in") {
    fmt.Println("see:", filepath.Join(inst.Dir, "ha.stderr.log"))
}

haPID := filepath.Join(instDir, "ha.pid")
if _, err := os.Stat(haPID); err == nil { /* hostagent already up or stale */ }

if err != nil && strings.Contains(err.Error(), "did not start up in") {
    b, _ := os.ReadFile(filepath.Join(instDir, "ha.stderr.log"))
    return fmt.Errorf("hostagent never registered: %w\n%s", err, b)
}

When it happens

Trigger: Calling `limactl start` (which invokes StartWithPaths -> waitHostAgentStart) when the hostagent fails to launch at all: binary not found, exec permission error, or immediate crash before writing the PID file.

Common situations: Stale/locked ~/.lima directory, limactl binary moved after install, antivirus blocking the process, or extremely slow disk making startup exceed the deadline.

Related errors

• did not receive an event with the `running` status
• failed to get Info from %#q: %w
• another hostagent may already be running with pid %d (pidfil
• failed to determine if another hostagent is running: %w
• pidfile %#q already exists

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