lima-vm/lima · error

vz driver state stopped

Error message

vz driver state stopped

What it means

The VZ driver watches VM state changes; when the underlying VZ virtual machine transitions to a stopped state, the wrapper marks itself stopped, unexposes the SSH port, stops usernet, and sends errors.New("vz driver state stopped") through the error channel. This is the driver's normal shutdown/propagation signal when the VM exits or crashes.

Source

Thrown at pkg/driver/vz/vm_darwin.go:168

									Reason: "Failed to wait for guest SSH server",
								})
							}
						}
						err := usernetClient.ConfigureDriver(ctx, inst, usernetSSHLocalPort)
						if err != nil {
							sendErrCh <- err
						}
					}()
				case vz.VirtualMachineStateStopped:
					logrus.Info("[VZ] - vm state change: stopped")
					wrapper.mu.Lock()
					wrapper.stopped = true
					wrapper.mu.Unlock()
					_ = usernetClient.UnExposeSSH(inst.SSHLocalPort)
					if stopUsernet != nil {
						stopUsernet()
					}
					sendErrCh <- errors.New("vz driver state stopped")
				default:
					logrus.Debugf("[VZ] - vm state change: %#q", newState)
				}
			}
		}
	}()
	return wrapper, notifySSHLocalPortAccessible, sendErrCh, err
}

func startUsernet(ctx context.Context, inst *limatype.Instance) (*usernet.Client, context.CancelFunc, error) {
	if firstUsernetIndex := limayaml.FirstUsernetIndex(inst.Config); firstUsernetIndex != -1 {
		nwName := inst.Config.Networks[firstUsernetIndex].Lima
		return usernet.NewClientByName(nwName), nil, nil
	}
	// Start a in-process gvisor-tap-vsock
	endpointSock, err := usernet.SockWithDirectory(inst.Dir, "", usernet.EndpointSock)
	if err != nil {
		return nil, nil, err

View on GitHub (pinned to dd909d0973)

Solutions

1. Inspect the instance logs (`limactl shell` unavailable now; check ~/.lima/<instance>/ha.stderr.log or journal) to learn why the VM stopped.
2. Restart with `limactl start <instance>`.
3. If the VM stopped unexpectedly, check macOS Virtualization framework logs and available memory/disk.
4. Treat it as expected lifecycle event if the guest deliberately shut down; the hostagent will reconcile instance state.

// Go: consume the driver error channel
for err := range errCh {
    if err != nil && err.Error() == "vz driver state stopped" {
        log.Info("VM stopped; reconciling instance state")
        break
    }
}

When it happens

Trigger: The VZ VM process halts unexpectedly (guest shutdown, VZ runtime error, crash), causing the state-change watcher to observe .stopped and emit this error to the instance monitor.

Common situations: Guest-initiated shutdown; VZ aborting the VM due to invalid configuration or resource exhaustion; the VM crashing during boot; user stopping the instance from inside the guest.

Related errors

• failed to run %v: %w (output=%s)
• vz timeout while waiting for stop status
• vz: CanRequestStop is not supported
• failed to get macOS product version: %w
• failed to create a new rosetta directory share caching optio

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