{"record":{"id":"20ef364e7d697c47","repo":"lima-vm/lima","slug":"rungui-is-not-supported-for-the-given-driver-s-20ef36","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/wsl2/wsl_driver_windows.go","lineNumber":294,"sourceCode":"\t\tdistroName,\n\t\terrCh,\n\t); err != nil {\n\t\treturn nil, err\n\t}\n\n\tkeepAlive(ctx, distroName, errCh)\n\n\treturn errCh, err\n}\n\n// CanRunGUI requires WSLg, which requires specific version of WSL2 to be installed.\n// TODO: Add check and add support for WSLg (instead of VNC) to hostagent.\nfunc (l *LimaWslDriver) canRunGUI() bool {\n\treturn false\n}\n\nfunc (l *LimaWslDriver) RunGUI(_ context.Context) error {\n\treturn fmt.Errorf(\"RunGUI is not supported for the given driver '%s' and display '%s'\", \"wsl\", *l.Instance.Config.Video.Display)\n}\n\nfunc (l *LimaWslDriver) Stop(ctx context.Context) error {\n\tlogrus.Info(\"Shutting down WSL2 VM\")\n\tdistroName := \"lima-\" + l.Instance.Name\n\treturn stopVM(ctx, distroName)\n}\n\n// GuestAgentConn returns the guest agent connection, or nil (if forwarded by ssh).\n// As of 08-01-2024, github.com/mdlayher/vsock does not natively support vsock on\n// Windows, so use the winio library to create the connection.\nfunc (l *LimaWslDriver) GuestAgentConn(ctx context.Context) (net.Conn, string, error) {\n\tVMIDStr, err := windows.GetInstanceVMID(ctx, fmt.Sprintf(\"lima-%s\", l.Instance.Name))\n\tif err != nil {\n\t\treturn nil, \"\", err\n\t}\n\tVMIDGUID, err := guid.FromString(VMIDStr)\n\tif err != nil {","sourceCodeStart":276,"sourceCodeEnd":312,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/driver/wsl2/wsl_driver_windows.go#L276-L312","documentation":"RunGUI on the WSL2 driver always fails: canRunGUI() is hardcoded false (no VNC/WSLg support wired into the hostagent yet), so the method returns an error naming driver 'wsl' and the configured video display.","triggerScenarios":"Calling limactl start with a GUI request (e.g. `limactl start --gui` or config that triggers hostagent RunGUI) on an instance using the wsl2 driver. The display string comes from l.Instance.Config.Video.Display.","commonSituations":"Running `limactl start <instance> --gui vnc` on Windows with wsl2; scripts that unconditionally request GUI; expecting WSLg to be integrated.","solutions":["Start the instance without the GUI flag and use CLI/SSH access instead","Use a driver that supports RunGUI (e.g. qemu with VNC) if a graphical console is required","Run graphical apps via WSLg directly (native WSL GUI support) rather than Lima's RunGUI"],"exampleFix":"// before\nerr := limactl(\"start\", inst, \"--gui\")\n// after\nerr := limactl(\"start\", inst) // GUI unsupported on wsl2; use ssh/WSLg","handlingStrategy":"fallback","validationCode":"// callers can check the driver's capability first\nfunc guiSupported(vmType string) bool { return vmType != \"wsl2\" }\n// skip --gui when vmType is wsl2","typeGuard":"func canRunGUIFor(instance *limatype.Instance) bool {\n\treturn instance.VMType != \"wsl2\"\n}","tryCatchPattern":"if err := driver.RunGUI(ctx); err != nil {\n\tif strings.Contains(err.Error(), \"RunGUI is not supported\") {\n\t\tlog.Println(\"GUI unavailable on wsl2; falling back to shell/SSH access\")\n\t\treturn nil\n\t}\n\treturn err\n}","preventionTips":["Do not pass --gui when vmType is wsl2","Use native WSLg for graphical Linux apps on Windows","Gate GUI startup behind a driver-capability check in scripts"],"tags":["wsl2","gui","vnc"],"backgroundTag":"unsupported-driver-operation","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}