AppImage bundles libwayland-client.so.0, breaking Mesa EGL — blank window with EGL_BAD_PARAMETER

[AlpSha]

Summary

The v0.6.0 AppImage opens a window that never paints anything, and prints:

Could not create default EGL display: EGL_BAD_PARAMETER. Aborting...

The cause is that the AppImage bundles libwayland-client.so.0 from the Ubuntu 22.04 build runner (wayland 1.20). That library is on the official AppImage excludelist precisely because bundling it breaks Mesa.

Environment

• whatRust v0.6.0 (whatRust.AppImage)
• Arch-based distro (CachyOS), kernel 6.17
• Mesa 26.1.5, wayland 1.25.0, AMD Radeon RX 6800 (radeonsi)
• Wayland session (niri); the app runs through XWayland because AppRun forces GDK_BACKEND=x11
• Host webkit2gtk-4.1 2.52.5

Root cause

apprun-hooks/linuxdeploy-plugin-gtk.sh / AppRun.wrapped prepend the bundle's library directory to LD_LIBRARY_PATH, so every process in the tree resolves libwayland-client.so.0 to the bundled Ubuntu 22.04 copy instead of the host's.

Mesa 26.x's libEGL_mesa.so.0 requires wl_fixes_interface, a symbol introduced in wayland 1.23. The bundled 1.20 copy doesn't export it, so libglvnd fails to load the Mesa EGL vendor entirely:

$ LD_DEBUG=libs LD_LIBRARY_PATH=<AppDir>/usr/lib ./egltest
  find library=libEGL_mesa.so.0 [0]; searching
   trying file=<AppDir>/usr/lib/libEGL_mesa.so.0
   trying file=/usr/lib/libEGL_mesa.so.0
  /usr/lib/libEGL_mesa.so.0: error: symbol lookup error: undefined symbol: wl_fixes_interface (fatal)

With no vendor loaded, EGL reports no platforms at all and the default display request fails. Minimal reproducer (eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS) + eglGetDisplay(EGL_DEFAULT_DISPLAY)):

=== host environment ===
client extensions: EGL_EXT_device_base EGL_EXT_device_enumeration ... EGL_MESA_platform_surfaceless
eglGetDisplay(EGL_DEFAULT_DISPLAY) = 0x55f478d7cd70, err=0x3000   # EGL_SUCCESS
eglInitialize=1 err=0x3000

=== with the AppImage's LD_LIBRARY_PATH ===
client extensions:                                                # empty
eglGetDisplay(EGL_DEFAULT_DISPLAY) = (nil), err=0x300c            # EGL_BAD_PARAMETER

WebKitGTK then aborts its rendering process. The window is still created and mapped by GTK, which is why it appears but stays blank — only WebKitNetworkProcess survives; no WebKitWebProcess ever comes up.

Confirmation

Preloading the host library so it claims the SONAME first fixes it completely:

LD_PRELOAD=/usr/lib/libwayland-client.so.0 ./whatRust.AppImage

With that, the EGL error is gone, WebKitWebProcess starts and stays alive with libgallium-26.1.5 loaded and /dev/dri/renderD128 open, and the app renders normally with GPU acceleration.

Suggested fix

Exclude libwayland-client.so.0 (and the other libwayland-* copies) from the bundle in the release build. The upstream excludelist entry documents this exact failure mode:

libwayland-client.so.0
# https://github.com/AppImageCommunity/pkg2appimage/pull/559
# https://gitlab.freedesktop.org/mesa/mesa/-/issues/11316
# New version of Mesa has some dependency issues with libwayland-client if it is bundled

Since .github/workflows/release.yml builds on ubuntu-22.04 via tauri-apps/tauri-action@v0, the cleanest fix is to have the AppImage step honour the excludelist, or to delete usr/lib/libwayland-* from the AppDir before the AppImage is packed.

This will affect every user on a distro with Mesa 25.1+ / wayland 1.23+, which by now is most rolling and recent releases — so the blank window is likely to be reported more often as distros update.

Note on a common misdiagnosis

The usual advice for a blank Tauri window (WEBKIT_DISABLE_DMABUF_RENDERER=1, or blaming the Wayland/X11 backend or a multi-GPU setup) does not apply here. The host EGL stack is healthy on all platforms (GBM, Wayland, X11), and AppRun already forces the X11 backend. The distinguishing symptom is the empty EGL client-extension string under the bundle's LD_LIBRARY_PATH.