lima-vm/lima · error

failed to connect to %#q: %w

Error message

failed to connect to %#q: %w

What it means

During instance inspection (pkg/store/instance.go Inspect), Lima tried to create a client to the instance's host agent Unix socket but the connection attempt failed at the socket/client level. The instance is marked StatusBroken and the wrapped OS/gRPC error is appended to inst.Errors. This usually means the host agent socket does not exist or is stale (host agent crashed or was killed).

Source

Thrown at pkg/store/instance.go:76

	}
	inst.Config = y
	inst.Arch = *y.Arch
	inst.VMType = *y.VMType
	inst.SSHAddress = "127.0.0.1"
	inst.SSHLocalPort = *y.SSH.LocalPort // maybe 0
	inst.SSHConfigFile = filepath.Join(instDir, filenames.SSHConfig)
	inst.HostAgentPID, err = ReadPIDFile(filepath.Join(instDir, filenames.HostAgentPID))
	if err != nil {
		inst.Status = limatype.StatusBroken
		inst.Errors = append(inst.Errors, err)
	}

	if inst.HostAgentPID != 0 {
		haSock := filepath.Join(instDir, filenames.HostAgentSock)
		haClient, err := hostagentclient.NewHostAgentClient(haSock)
		if err != nil {
			inst.Status = limatype.StatusBroken
			inst.Errors = append(inst.Errors, fmt.Errorf("failed to connect to %#q: %w", haSock, err))
		} else {
			ctx, cancel := context.WithTimeout(ctx, 3*time.Second)
			defer cancel()
			info, err := haClient.Info(ctx)
			if err != nil {
				inst.Status = limatype.StatusBroken
				inst.Errors = append(inst.Errors, fmt.Errorf("failed to get Info from %#q: %w", haSock, err))
			} else {
				inst.SSHLocalPort = info.SSHLocalPort
				inst.AutoStartedIdentifier = info.AutoStartedIdentifier
			}
		}
	}
	if inst.SSHLocalPort == 0 {
		sshConfigPath := filepath.Join(instDir, filenames.SSHConfig)
		if port, err := sshPortFromConfig(sshConfigPath); err == nil {
			inst.SSHLocalPort = port
		} else if !errors.Is(err, os.ErrNotExist) {

View on GitHub (pinned to dd909d0973)

Solutions

1. Run `limactl stop <instance>` then `limactl start <instance>` to clear the stale PID/socket state
2. If stop hangs, remove the stale socket and PID files under ~/.lima/<instance> (ha.pid, host agent sock) and restart
3. Verify LIMA_HOME points to the correct instance directory
4. Check hostagent logs in ~/.lima/<instance>/ha_stderr.log for the underlying crash cause
5. Check filesystem permissions on the socket file

Example fix

// before: inspect shows broken instance with connection error
limactl list  # instance shows Broken
// after
limactl stop broken-vm; limactl start broken-vm

// Before relying on an instance, verify the host agent socket exists
haSock := filepath.Join(limaHome, instName, "ha.sock")
if _, err := os.Stat(haSock); err != nil {
    // socket stale/missing: treat instance as stopped/broken, do not call Inspect-dependent logic
}

inst, err := store.Inspect(ctx, instDir)
if err != nil {
    for _, e := range inst.Errors {
        var opErr *net.OpError
        if errors.As(e, &opErr) {
            // stale socket: stop+start the instance
        }
    }
}

When it happens

Trigger: Inspect() is called on an instance whose HostAgentPID is non-zero (a PID file exists) but the host agent socket at <instDir>/filenames.HostAgentSock cannot be dialed: socket file missing, stale socket after a crash, permission denied on the socket, or socket path deleted.

Common situations: VM was killed or the machine rebooted leaving a stale PID file; hostagent process crashed mid-run; ~/.lima directory partially deleted or moved; running limactl inside a container/sandbox without access to the Unix socket; wrong LIMA_HOME pointing at another user's instance dir.

Related errors

• host agent is running but driver is not
• field `%s.guestSocket` must be an absolute path, but is %#q
• field `%s.guestSocket` can only be mapped to a single port o
• field `%s.hostSocket` must be an absolute path, but is %#q
• field `%s.hostSocket` can only be mapped from a single port

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