{"record":{"id":"faaf413b839aadca","repo":"lima-vm/lima","slug":"rungui-is-not-supported-for-the-given-driver-s-faaf41","errorCode":null,"errorMessage":"RunGUI is not supported for the given driver '%s' and display '%s'","messagePattern":"RunGUI is not supported for the given driver '(.+?)' and display '(.+?)'","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/driver/vz/vz_driver_darwin.go","lineNumber":484,"sourceCode":"\n\treturn errCh, nil\n}\n\nfunc (l *LimaVzDriver) canRunGUI() bool {\n\tswitch *l.Instance.Config.Video.Display {\n\tcase \"vz\", \"default\":\n\t\treturn true\n\tdefault:\n\t\treturn false\n\t}\n}\n\nfunc (l *LimaVzDriver) RunGUI(_ context.Context) error {\n\tif l.canRunGUI() {\n\t\ttitle := fmt.Sprintf(\"Lima: %s\", l.Instance.Name)\n\t\treturn l.machine.StartGraphicApplication(1920, 1200, vz.WithWindowTitle(title))\n\t}\n\treturn fmt.Errorf(\"RunGUI is not supported for the given driver '%s' and display '%s'\", \"vz\", *l.Instance.Config.Video.Display)\n}\n\nfunc (l *LimaVzDriver) requestStopViaSSH(ctx context.Context) error {\n\tsshExe, err := sshutil.NewSSHExe()\n\tif err != nil {\n\t\treturn err\n\t}\n\tcmd := exec.CommandContext(ctx, sshExe.Exe,\n\t\tappend(sshExe.Args, \"-F\", l.Instance.SSHConfigFile, l.Instance.Hostname, \"--\",\n\t\t\t\"sudo\", \"/sbin/shutdown\", \"-h\", \"now\")...)\n\tlogrus.Infof(\"Running shutdown command in the VM: %v\", cmd.Args)\n\tif out, err := cmd.CombinedOutput(); err != nil {\n\t\treturn fmt.Errorf(\"failed to run %v: %w (output=%s)\", cmd.Args, err, string(out))\n\t}\n\treturn nil\n}\n\nfunc (l *LimaVzDriver) Stop(ctx context.Context) error {","sourceCodeStart":466,"sourceCodeEnd":502,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/driver/vz/vz_driver_darwin.go#L466-L502","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove `video.display: none` from the config so it defaults to a GUI-capable display","Set `video.display: vz` (or 'default') and restart the instance","Start without --gui and use SSH instead"],"exampleFix":"# before\nvideo:\n  display: none\n# after\nvideo:\n  display: default","handlingStrategy":"validation","validationCode":"if guiRequested && cfg.Video.Display != nil && *cfg.Video.Display == \"none\" {\n    // unset video.display or set it to \"vz\"/\"default\" before --gui\n}","typeGuard":"func canRunGUI(display string) bool {\n    return display == \"\" || display == \"vz\" || display == \"default\"\n}","tryCatchPattern":"if err := driver.RunGUI(ctx); err != nil {\n    if strings.Contains(err.Error(), \"RunGUI is not supported\") {\n        // start headless instead, or fix video.display and restart\n    }\n}","preventionTips":["Do not set video.display: none if you plan to use --gui","Use --headless explicitly for CI configs with display: none","Check the template for display settings copied from headless setups"],"tags":["macos","vz","gui","config-validation"],"backgroundTag":"gui-not-supported","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}