{"record":{"id":"2ecc8997f3e3b4a3","repo":"lima-vm/lima","slug":"unable-to-connect-to-guest-agent-via-vsock-port-22","errorCode":null,"errorMessage":"unable to connect to guest agent via vsock port 2222","messagePattern":"unable to connect to guest agent via vsock port 2222","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/driver/vz/vz_driver_darwin.go","lineNumber":547,"sourceCode":"\t\t\t\tstopped := l.machine.stopped\n\t\t\t\tl.machine.mu.Unlock()\n\t\t\t\tif stopped {\n\t\t\t\t\treturn nil\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\treturn errors.New(\"vz: CanRequestStop is not supported\")\n}\n\nfunc (l *LimaVzDriver) GuestAgentConn(_ context.Context) (net.Conn, string, error) {\n\tfor _, socket := range l.machine.SocketDevices() {\n\t\tconnect, err := socket.Connect(uint32(l.vSockPort))\n\t\treturn connect, \"vsock\", err\n\t}\n\n\treturn nil, \"\", errors.New(\"unable to connect to guest agent via vsock port 2222\")\n}\n\nfunc (l *LimaVzDriver) Info(_ context.Context) driver.Info {\n\tvar info driver.Info\n\n\tinfo.Name = \"vz\"\n\tinfo.VsockPort = l.vSockPort\n\tinfo.VirtioPort = l.virtioPort\n\tif l.Instance != nil {\n\t\tinfo.InstanceDir = l.Instance.Dir\n\t}\n\n\tvar guiFlag bool\n\tif l.Instance != nil {\n\t\tguiFlag = l.canRunGUI()\n\t}\n\tinfo.Features = driver.DriverFeatures{\n\t\tDynamicSSHAddress:     false,","sourceCodeStart":529,"sourceCodeEnd":565,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/driver/vz/vz_driver_darwin.go#L529-L565","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure the instance is running: `limactl start <instance>` and wait for full boot before issuing commands","Retry after a short delay — during early boot the socket device may not be registered yet","Check `limactl list` for instance state; restart the instance if it shows as broken/exited","Update Lima; confirm the guest agent is installed in the disk image (custom/older images may lack it)","If using a custom rootfs/template, verify it provisions the lima guest agent and vsock support"],"exampleFix":"// before\nconn, _, err := driver.GuestAgentConn(ctx) // err: unable to connect ... 2222\n// after\nif instState != \"Running\" {\n    return errors.New(\"start the instance before requesting the guest agent connection\")\n}\nconn, _, err := driver.GuestAgentConn(ctx)","handlingStrategy":"retry","validationCode":"// wait for the instance to be fully running first\nfor i := 0; i < 30; i++ {\n    if instanceState(inst) == \"Running\" { break }\n    time.Sleep(time.Second)\n}","typeGuard":null,"tryCatchPattern":"conn, proto, err := driver.GuestAgentConn(ctx)\nif err != nil {\n    time.Sleep(500 * time.Millisecond)\n    conn, proto, err = driver.GuestAgentConn(ctx) // boot races resolve on retry\n}\nif err != nil { return fmt.Errorf(\"guest agent unavailable: %w\", err) }","preventionTips":["Only call guest-agent APIs after the instance reports Running","Don't use disk images missing the Lima guest agent","Restart broken instances rather than poking their sockets","Check guestagent logs if connections repeatedly fail"],"tags":["vsock","vz-driver","guestagent","macos"],"backgroundTag":"guest-agent-connection-failed","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}