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

Source

Thrown at pkg/driver/wsl2/wsl_driver_windows.go:294

		distroName,
		errCh,
	); err != nil {
		return nil, err
	}

	keepAlive(ctx, distroName, errCh)

	return errCh, err
}

// CanRunGUI requires WSLg, which requires specific version of WSL2 to be installed.
// TODO: Add check and add support for WSLg (instead of VNC) to hostagent.
func (l *LimaWslDriver) canRunGUI() bool {
	return false
}

func (l *LimaWslDriver) RunGUI(_ context.Context) error {
	return fmt.Errorf("RunGUI is not supported for the given driver '%s' and display '%s'", "wsl", *l.Instance.Config.Video.Display)
}

func (l *LimaWslDriver) Stop(ctx context.Context) error {
	logrus.Info("Shutting down WSL2 VM")
	distroName := "lima-" + l.Instance.Name
	return stopVM(ctx, distroName)
}

// GuestAgentConn returns the guest agent connection, or nil (if forwarded by ssh).
// As of 08-01-2024, github.com/mdlayher/vsock does not natively support vsock on
// Windows, so use the winio library to create the connection.
func (l *LimaWslDriver) GuestAgentConn(ctx context.Context) (net.Conn, string, error) {
	VMIDStr, err := windows.GetInstanceVMID(ctx, fmt.Sprintf("lima-%s", l.Instance.Name))
	if err != nil {
		return nil, "", err
	}
	VMIDGUID, err := guid.FromString(VMIDStr)
	if err != nil {

View on GitHub (pinned to dd909d0973)

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

Example fix

// before
err := limactl("start", inst, "--gui")
// after
err := limactl("start", inst) // GUI unsupported on wsl2; use ssh/WSLg

Defensive patterns

Strategy: fallback

Validate before calling

// callers can check the driver's capability first
func guiSupported(vmType string) bool { return vmType != "wsl2" }
// skip --gui when vmType is wsl2

Type guard

func canRunGUIFor(instance *limatype.Instance) bool {
	return instance.VMType != "wsl2"
}

Try / catch

if err := driver.RunGUI(ctx); err != nil {
	if strings.Contains(err.Error(), "RunGUI is not supported") {
		log.Println("GUI unavailable on wsl2; falling back to shell/SSH access")
		return nil
	}
	return err
}

Prevention

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

When it happens

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

Common situations: Running `limactl start <instance> --gui vnc` on Windows with wsl2; scripts that unconditionally request GUI; expecting WSLg to be integrated.

Related errors

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