{"record":{"id":"2eca2ff719995c00","repo":"lima-vm/lima","slug":"vz-timeout-while-waiting-for-stop-status","errorCode":null,"errorMessage":"vz timeout while waiting for stop status","messagePattern":"vz timeout while waiting for stop status","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/driver/vz/vz_driver_darwin.go","lineNumber":526,"sourceCode":"\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\n\t\tif *l.Instance.Config.OS == limatype.DARWIN {\n\t\t\t// macOS VM does not respond to l.machine.RequestStop(),\n\t\t\t// so we need to run `shutdown -h now` in the VM via SSH for graceful shutdown.\n\t\t\tif err := l.requestStopViaSSH(ctx); err != nil {\n\t\t\t\tlogrus.WithError(err).Warn(\"Failed to request shutdown via SSH\")\n\t\t\t}\n\t\t}\n\n\t\t// Most Linux machines shutdown within 5 seconds, but macOS machines can take longer.\n\t\ttimeout := time.After(30 * time.Second)\n\t\tticker := time.NewTicker(500 * time.Millisecond)\n\t\tfor {\n\t\t\tselect {\n\t\t\tcase <-timeout:\n\t\t\t\treturn errors.New(\"vz timeout while waiting for stop status\")\n\t\t\tcase <-ticker.C:\n\t\t\t\tl.machine.mu.Lock()\n\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","sourceCodeStart":508,"sourceCodeEnd":544,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/driver/vz/vz_driver_darwin.go#L508-L544","documentation":"After requesting a graceful stop, the VZ driver polls the machine's `stopped` flag every 500ms for up to 30 seconds. If the VZ virtual machine does not report a stopped state within that window, the driver gives up with this timeout error instead of hanging forever.","triggerScenarios":"Stop() is called, the shutdown request was sent, but the guest does not power off within 30 seconds — e.g. shutdown hung, the VZ stop callback never fired, or the machine object's stopped flag was never set.","commonSituations":"Guest with long-running services that block shutdown (slow unmount, systemd stop timeouts); macOS guests that take longer than the comment-documented 5s; a VM whose canRequestStop callback path silently failed; VZ framework quirks after host sleep/resume.","solutions":["Retry `limactl stop <instance>` — a second attempt usually sees the VM already stopped or shuts it down","Use `limactl stop --force <instance>` (or delete the vmstore/kill the VM process) to hard-stop","Check the guest logs (`limactl shell` if still reachable, or serial log) for why shutdown stalled","Increase timeouts or ensure guest services exit cleanly (systemd timeout tweaks) if this recurs regularly","Update Lima/Virtualization.framework; some VZ stop-callback issues are fixed in newer macOS releases"],"exampleFix":"// before\nlimactl stop myvm   // hangs then: vz timeout while waiting for stop status\n// after\nlimactl stop --force myvm","handlingStrategy":"retry","validationCode":"// ensure guest services can stop quickly\nlimactl shell inst -- systemctl list-jobs // check for stuck stop jobs before planned shutdowns","typeGuard":null,"tryCatchPattern":"err := driver.Stop(ctx)\nif err != nil && strings.Contains(err.Error(), \"timeout while waiting for stop\") {\n    time.Sleep(2 * time.Second)\n    err = driver.Stop(ctx) // usually the VM is now stopped\n}","preventionTips":["Give guests time to shut down; avoid stopping immediately after heavy I/O","Reduce systemd stop timeouts in the guest for fast-shutdown services","On macOS guests, expect longer shutdown times than Linux","Keep macOS/Lima updated for VZ stop-callback fixes"],"tags":["timeout","vz-driver","shutdown","macos"],"backgroundTag":"vm-shutdown-timeout","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}