lima-vm/lima · error

unable to connect to guest agent via vsock port 2222

Error message

unable to connect to guest agent via vsock port 2222

What it means

GuestAgentConn looks for a VZ socket device and connects to the guest agent over vsock on port 2222. If the machine has no usable socket devices to iterate (e.g. the VM is not running or has no socket device), the driver returns this error with a nil connection. The hardcoded '2222' is descriptive of the standard vsock port.

Source

Thrown at pkg/driver/vz/vz_driver_darwin.go:547

				stopped := l.machine.stopped
				l.machine.mu.Unlock()
				if stopped {
					return nil
				}
			}
		}
	}

	return errors.New("vz: CanRequestStop is not supported")
}

func (l *LimaVzDriver) GuestAgentConn(_ context.Context) (net.Conn, string, error) {
	for _, socket := range l.machine.SocketDevices() {
		connect, err := socket.Connect(uint32(l.vSockPort))
		return connect, "vsock", err
	}

	return nil, "", errors.New("unable to connect to guest agent via vsock port 2222")
}

func (l *LimaVzDriver) Info(_ context.Context) driver.Info {
	var info driver.Info

	info.Name = "vz"
	info.VsockPort = l.vSockPort
	info.VirtioPort = l.virtioPort
	if l.Instance != nil {
		info.InstanceDir = l.Instance.Dir
	}

	var guiFlag bool
	if l.Instance != nil {
		guiFlag = l.canRunGUI()
	}
	info.Features = driver.DriverFeatures{
		DynamicSSHAddress:     false,

View on GitHub (pinned to dd909d0973)

Solutions

1. Ensure the instance is running: `limactl start <instance>` and wait for full boot before issuing commands
2. Retry after a short delay — during early boot the socket device may not be registered yet
3. Check `limactl list` for instance state; restart the instance if it shows as broken/exited
4. Update Lima; confirm the guest agent is installed in the disk image (custom/older images may lack it)
5. If using a custom rootfs/template, verify it provisions the lima guest agent and vsock support

Example fix

// before
conn, _, err := driver.GuestAgentConn(ctx) // err: unable to connect ... 2222
// after
if instState != "Running" {
    return errors.New("start the instance before requesting the guest agent connection")
}
conn, _, err := driver.GuestAgentConn(ctx)

// wait for the instance to be fully running first
for i := 0; i < 30; i++ {
    if instanceState(inst) == "Running" { break }
    time.Sleep(time.Second)
}

conn, proto, err := driver.GuestAgentConn(ctx)
if err != nil {
    time.Sleep(500 * time.Millisecond)
    conn, proto, err = driver.GuestAgentConn(ctx) // boot races resolve on retry
}
if err != nil { return fmt.Errorf("guest agent unavailable: %w", err) }

When it happens

Trigger: GuestAgentConn is called while the VZ machine has no SocketDevices — typically because the VM is stopped, still starting, or was created without the socket device — so the loop body never executes.

Common situations: Calling guest-agent dependent features (port forwarding, shell) before the VM finished booting; instance crashed/exited so devices were torn down; using the driver programmatically without calling Start first; VZ failed to create the socket device during boot.

Related errors

• failed to get macOS product version: %w
• failed to create a new rosetta directory share caching optio
• cannot enable nested virtualization: %w
• networks.yaml '%s' configuration is only supported on macOS
• failed to create host audio output stream: %w

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