What causes "vz timeout while waiting for stop status" in lima-vm/lima?

Retry `limactl stop ` — a second attempt usually sees the VM already stopped or shuts it down

vz timeout while waiting for stop status

Error message

vz timeout while waiting for stop status

What it means

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.

Source

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

		if err != nil {
			return err
		}

		if *l.Instance.Config.OS == limatype.DARWIN {
			// macOS VM does not respond to l.machine.RequestStop(),
			// so we need to run `shutdown -h now` in the VM via SSH for graceful shutdown.
			if err := l.requestStopViaSSH(ctx); err != nil {
				logrus.WithError(err).Warn("Failed to request shutdown via SSH")
			}
		}

		// Most Linux machines shutdown within 5 seconds, but macOS machines can take longer.
		timeout := time.After(30 * time.Second)
		ticker := time.NewTicker(500 * time.Millisecond)
		for {
			select {
			case <-timeout:
				return errors.New("vz timeout while waiting for stop status")
			case <-ticker.C:
				l.machine.mu.Lock()
				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

View on GitHub (pinned to dd909d0973)

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

Example fix

// before
limactl stop myvm   // hangs then: vz timeout while waiting for stop status
// after
limactl stop --force myvm

Defensive patterns

Strategy: retry

Validate before calling

// ensure guest services can stop quickly
limactl shell inst -- systemctl list-jobs // check for stuck stop jobs before planned shutdowns

Try / catch

err := driver.Stop(ctx)
if err != nil && strings.Contains(err.Error(), "timeout while waiting for stop") {
    time.Sleep(2 * time.Second)
    err = driver.Stop(ctx) // usually the VM is now stopped
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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