lima-vm/lima · error

RunGUI is not supported for the given driver '%s' and displa

Error message

RunGUI is not supported for the given driver '%s' and display '%s'

What it means

RunGUI opens the Virtualization.framework graphic application window, but only when `canRunGUI()` reports the configured video display is GUI-capable. If not, it returns this error naming the driver ('vz') and the configured `video.display` value.

Source

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

	return errCh, nil
}

func (l *LimaVzDriver) canRunGUI() bool {
	switch *l.Instance.Config.Video.Display {
	case "vz", "default":
		return true
	default:
		return false
	}
}

func (l *LimaVzDriver) RunGUI(_ context.Context) error {
	if l.canRunGUI() {
		title := fmt.Sprintf("Lima: %s", l.Instance.Name)
		return l.machine.StartGraphicApplication(1920, 1200, vz.WithWindowTitle(title))
	}
	return fmt.Errorf("RunGUI is not supported for the given driver '%s' and display '%s'", "vz", *l.Instance.Config.Video.Display)
}

func (l *LimaVzDriver) requestStopViaSSH(ctx context.Context) error {
	sshExe, err := sshutil.NewSSHExe()
	if err != nil {
		return err
	}
	cmd := exec.CommandContext(ctx, sshExe.Exe,
		append(sshExe.Args, "-F", l.Instance.SSHConfigFile, l.Instance.Hostname, "--",
			"sudo", "/sbin/shutdown", "-h", "now")...)
	logrus.Infof("Running shutdown command in the VM: %v", cmd.Args)
	if out, err := cmd.CombinedOutput(); err != nil {
		return fmt.Errorf("failed to run %v: %w (output=%s)", cmd.Args, err, string(out))
	}
	return nil
}

func (l *LimaVzDriver) Stop(ctx context.Context) error {

View on GitHub (pinned to dd909d0973)

Solutions

1. Remove `video.display: none` from the config so it defaults to a GUI-capable display
2. Set `video.display: vz` (or 'default') and restart the instance
3. Start without --gui and use SSH instead

Example fix

# before
video:
  display: none
# after
video:
  display: default

if guiRequested && cfg.Video.Display != nil && *cfg.Video.Display == "none" {
    // unset video.display or set it to "vz"/"default" before --gui
}

func canRunGUI(display string) bool {
    return display == "" || display == "vz" || display == "default"
}

if err := driver.RunGUI(ctx); err != nil {
    if strings.Contains(err.Error(), "RunGUI is not supported") {
        // start headless instead, or fix video.display and restart
    }
}

When it happens

Trigger: Running `limactl start --gui` (or calling RunGUI) on a VZ instance whose `video.display` is set to 'none' (or otherwise not 'vz'/'default'), so canRunGUI() is false.

Common situations: Templates that set `video.display: none` for headless use being started with --gui; users expecting a window while display is disabled; headless CI configs reused interactively.

Related errors

• `firmware.images` configuration is not supported for VZ driv
• unsupported arch: %#q
• field `vmOpts.vz.diskImageFormat` must be %#q or %#q, got %#
• invalid disk size %#q: %w
• unsupported disk format for macOS guest: %s

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