fix(linux): WebKitGTK EGL/DMA-BUF blank window on Linux (#106) - #107
Merged
Conversation
) WebKitGTK 2.42+ defaults to a DMA-BUF renderer that fails to create an EGL display on recent Linux GPU/driver stacks (NVIDIA, VMs, Mesa on Fedora 44 and openSUSE Tumbleweed), leaving an empty window and aborting with "Could not create default EGL display: EGL_BAD_PARAMETER". Force the legacy, non-accelerated path by setting WEBKIT_DISABLE_DMABUF_RENDERER=1 and WEBKIT_DISABLE_COMPOSITING_MODE=1 before the first webview spawns, only when the user has not already set them. Gated to target_os = "linux" (all distros and package formats; Android/iOS excluded); zero effect on Windows/macOS. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Vesperino
added a commit
that referenced
this pull request
Jun 7, 2026
The #106 WebKitGTK EGL/DMA-BUF fix merged to master via #107 without a version bump, so the release workflow stayed on v0.5.1 and the auto-updater never offered an update. Bump to v0.5.2 and add release notes so the already-merged fix ships as a new version. Security/dependency updates (#105) follow in v0.5.3. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Vesperino
added a commit
that referenced
this pull request
Jun 9, 2026
tauri-bundler's pinned linuxdeploy (built 2024-07-29) predates the excludelist entry for libwayland-client.so.0 (added 2024-11-03), so the AppImage shipped noble's wayland 1.22. Host Mesa >= 24.2 needs wl_display_create_queue_with_name (wayland 1.23); ld.so SONAME dedup binds libEGL_mesa to the stale bundled copy, the EGL vendor fails to load and WebKit's WebProcess aborts with "Could not create default EGL display: EGL_BAD_PARAMETER", leaving a blank window. Pre-seed tauri's tools cache with a pinned linuxdeploy that carries the fixed excludelist, assert the artifact after build, and add a PR smoke workflow building the AppImage. Reproduced and verified in a Fedora 44 container: vanilla v0.5.4 aborts; the same AppImage with libwayland-client removed runs. The WEBKIT_DISABLE_* overrides from #107 cannot gate this abort: since WebKitGTK 2.46 the WebProcess initializes EGL before the preference store is applied. Closes #106
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem (#106)
On Linux the AppImage opens an empty window and aborts in the terminal with:
Reported on openSUSE Tumbleweed and Fedora 44 — both ship WebKitGTK 2.42+, whose default DMA-BUF renderer fails EGL display creation on several GPU/driver stacks (NVIDIA, VMs, recent Mesa).
Fix
Before the first webview spawns (first statement of
run(), still single-threaded), on Linux only, set:WEBKIT_DISABLE_DMABUF_RENDERER=1— directly removes the EGL_BAD_PARAMETER abort; WebKit falls back to the non-DMA-BUF path (keeps accelerated compositing).WEBKIT_DISABLE_COMPOSITING_MODE=1— belt-and-suspenders for stacks where the GL compositing path also fails (NVIDIA/Wayland/X11 variants).Each is injected only when the user hasn't already set it, so an explicit
WEBKIT_DISABLE_*stays authoritative.Why it's universal across Linux
#[cfg(target_os = "linux")]→ every distro, every package format (AppImage/deb/rpm). Android/iOS excluded.Trade-off (worth noting)
WEBKIT_DISABLE_COMPOSITING_MODE=1is unconditional on Linux → it disables accelerated compositing even on healthy GPUs. This is a perf downgrade, not correctness, and negligible for a text + SVG (Mermaid) editor. Chosen for maximum compatibility since the failing stacks can't be reproduced on the dev machine.Tests
TDD (RED → GREEN). New unit tests in
src-tauri/src/lib.rs, compiled on every platform via the#[cfg(any(test, target_os = "linux"))]gate:webkit_override_applies_when_unset_or_blank— unset/empty/whitespace → inject.webkit_override_respects_explicit_user_value—"1"/"0"→ respect user.linux_webkit_overrides_target_known_egl_workaround_vars— exact var names/values + applier type-checks.cargo test --lib→ 52 passed, 0 failed, clean output (no warnings).Residual risk
The dev/CI host is Windows; the failure is Linux-only and was not run end-to-end here. The env-var workaround is the documented, ecosystem-standard fix for this exact error, but a one-off smoke test on Tumbleweed/Fedora 44 (window actually renders) would close the only remaining gap before release. A tiny minority of stacks could need extra vars (e.g.
LIBGL_ALWAYS_SOFTWARE) — not addressable without a repro box.🤖 Generated with Claude Code