fix(linux): apply WEBKIT_DISABLE_DMABUF_RENDERER on X11 for NVIDIA GPUs (#5295)

fix(linux): apply WEBKIT_DISABLE_DMABUF_RENDERER on X11 too for NVIDIA GPUs

The blank/white window bug (#4985) affects both X11 and Wayland sessions with
NVIDIA proprietary drivers, but the previous workaround only set
WEBKIT_DISABLE_DMABUF_RENDERER=1 on Wayland. Remove the session-type guard so
the env var is applied whenever the nvidia kernel module is present.

Also adds the same protection to the purego build variant (previously unhandled)
and documents the issue + automatic mitigation in the Linux troubleshooting guide.

Co-authored-by: wails-fleet-bot <noreply@wails-fleet.local>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: multica-agent <github@multica.ai>

Author: 4 people

docs/src/content/docs/guides/build/linux.mdx

@@ -195,6 +195,20 @@ sudo pacman -S base-devel
 
 Alternatively, run `wails3 task setup:docker` and the build system will use Docker automatically.
 
+### Blank or white window on NVIDIA GPU
+
+On Linux with NVIDIA proprietary drivers, Wails apps may show a blank or white window on startup. This is caused by a WebKitGTK bug where the DMA-BUF renderer fails with `gbm_bo_map()` against the NVIDIA proprietary driver (affects X11 and Wayland, driver versions 377–580+, GPUs from the 10 series and older GT 710).
+
+**Wails applies `WEBKIT_DISABLE_DMABUF_RENDERER=1` automatically** when it detects the NVIDIA kernel module (`/sys/module/nvidia`), so most users will not need to do anything.
+
+If you still see a blank window (for example in a container where the module path is not visible), set the environment variable manually before launching your app:
+
+```bash
+WEBKIT_DISABLE_DMABUF_RENDERER=1 ./myapp
+```
+
+Related upstream bugs: [WebKit #262607](https://bugs.webkit.org/show_bug.cgi?id=262607), [WebKit #180739](https://bugs.webkit.org/show_bug.cgi?id=180739).
+
 ### AppImage strip compatibility
 
 On modern Linux distributions (Arch Linux, Fedora 39+, Ubuntu 24.04+), system libraries are compiled with `.relr.dyn` ELF sections for more efficient relocations. The `linuxdeploy` tool used to create AppImages bundles an older `strip` binary that cannot process these modern sections.

v3/pkg/application/application_linux.go

@@ -59,12 +59,12 @@ func init() {
 		_ = os.Setenv("GDK_BACKEND", "x11")
 	}
 
-	// Disable DMA-BUF renderer on Wayland with NVIDIA to prevent "Error 71 (Protocol error)" crashes.
-	// This is a known WebKitGTK issue with NVIDIA proprietary drivers on Wayland.
+	// Disable DMA-BUF renderer on any session type with NVIDIA to prevent blank windows and
+	// "Error 71 (Protocol error)" crashes. NVIDIA proprietary drivers fail gbm_bo_map() when
+	// importing DMA-BUF, causing blank/white screens on both X11 and Wayland.
 	// See: https://bugs.webkit.org/show_bug.cgi?id=262607
-	if os.Getenv("WEBKIT_DISABLE_DMABUF_RENDERER") == "" &&
-		os.Getenv("XDG_SESSION_TYPE") == "wayland" &&
-		isNVIDIAGPU() {
+	// See: https://github.com/wailsapp/wails/issues/4985
+	if os.Getenv("WEBKIT_DISABLE_DMABUF_RENDERER") == "" && isNVIDIAGPU() {
 		_ = os.Setenv("WEBKIT_DISABLE_DMABUF_RENDERER", "1")
 	}
 }

v3/pkg/application/application_linux_gtk4.go

@@ -49,9 +49,12 @@ func init() {
 	fmt.Println("│  Please report issues: https://github.com/wailsapp/wails/issues/4957   │")
 	fmt.Println("└────────────────────────────────────────────────────────────────────────┘")
 
-	if os.Getenv("WEBKIT_DISABLE_DMABUF_RENDERER") == "" &&
-		os.Getenv("XDG_SESSION_TYPE") == "wayland" &&
-		isNVIDIAGPU() {
+	// Disable DMA-BUF renderer on any session type with NVIDIA to prevent blank windows and
+	// "Error 71 (Protocol error)" crashes. NVIDIA proprietary drivers fail gbm_bo_map() when
+	// importing DMA-BUF, causing blank/white screens on both X11 and Wayland.
+	// See: https://bugs.webkit.org/show_bug.cgi?id=262607
+	// See: https://github.com/wailsapp/wails/issues/4985
+	if os.Getenv("WEBKIT_DISABLE_DMABUF_RENDERER") == "" && isNVIDIAGPU() {
 		_ = os.Setenv("WEBKIT_DISABLE_DMABUF_RENDERER", "1")
 	}
 }

v3/pkg/application/linux_purego.go

@@ -233,6 +233,17 @@ var (
 func init() {
 	// needed for GTK4 to function
 	_ = os.Setenv("GDK_BACKEND", "x11")
+
+	// Disable DMA-BUF renderer on any session type with NVIDIA to prevent blank windows and
+	// "Error 71 (Protocol error)" crashes. NVIDIA proprietary drivers fail gbm_bo_map() when
+	// importing DMA-BUF, causing blank/white screens on both X11 and Wayland.
+	// See: https://bugs.webkit.org/show_bug.cgi?id=262607
+	// See: https://github.com/wailsapp/wails/issues/4985
+	if os.Getenv("WEBKIT_DISABLE_DMABUF_RENDERER") == "" {
+		if _, err := os.Stat("/sys/module/nvidia"); err == nil {
+			_ = os.Setenv("WEBKIT_DISABLE_DMABUF_RENDERER", "1")
+		}
+	}
 	var err error
 
 	// gtk, err = purego.Dlopen(gtk4, purego.RTLD_NOW|purego.RTLD_GLOBAL)