[AppImage] WebKitGTK EGL failure and hardcoded path conflicts on Arch Linux (Hyprland/Wayland)

[Aegirzs]

1. Summary/Title

The AppImage fails on Arch Linux (especially on Hyprland/Wayland) due to hardcoded relative paths and EGL negotiation conflicts with modern Mesa drivers (v25+).

With the technical guidance of Gemini (AI), we identified that the binary expects an Ubuntu-like file structure (/lib/x86_64-linux-gnu/) to spawn its child processes and fails to initialize DMA-BUF surfaces.

2. Environment

   OS: Arch Linux x86_64 (Kernel: 6.18.4-2-cachyos)

   CPU: AMD Ryzen 7 7800X3D (8 cores)

   GPU: AMD Radeon RX 6600 XT (Discrete) / AMD Ryzen 7 7800X3D (Integrated)

   WM: Hyprland 0.53.1 (Wayland)

   Mesa Version: 25.3.3-arch1.4 (Vulkan 1.4.328 / OpenGL 4.6)

   App Version: Quantframe 1.6.12 (AppImage)

3. Steps to Reproduce

   On an Arch Linux system running Hyprland, download the Quantframe_1.6.12_amd64.AppImage.

   Grant execution permissions and run it from the terminal.

   The application crashes during the WebKit initialization phase with the following logs:

    Could not create default EGL display: EGL_BAD_PARAMETER. Aborting...
   
    ERROR: Unable to spawn a new child process: Failed to spawn child process “././/lib/x86_64-linux-gnu/webkit2gtk-4.1/WebKitNetworkProcess” (No such file or directory)
   

4. Expected Behavior

The AppImage should resolve internal paths dynamically and initialize the WebKitGTK frontend using available system display protocols (Wayland or XWayland).

Technical Analysis & Solution (Aided by AI)

I was able to debug and resolve this issue with the guidance of Gemini. Since I don't have the deep technical background to trace syscalls manually, the AI guided me through using strace and analyzing environment variables to find the root cause.

Findings:

Hardcoded Paths: The application has hardcoded relative paths for WebKit subprocesses that follow the Debian/Ubuntu FHS (/lib/x86_64-linux-gnu/). Since Arch Linux does not use this structure, the application fails to "spawn" its networking and rendering processes.

EGL Parameter Conflict: There is a negotiation failure between the AppImage's internal EGL implementation and the modern Mesa 25.x drivers on Arch, specifically when attempting DMA-BUF rendering on Wayland.

The Fix: We extracted the AppImage and manually created a "mirror" of the expected Ubuntu path structure, linking it to the system's native WebKit files.

Extracting: ./Quantframe.AppImage --appimage-extract

Path Patching:

inside of squashfs-root directory

mkdir -p lib/x86_64-linux-gnu/webkit2gtk-4.1/injected-bundle/
ln -sf /usr/lib/webkit2gtk-4.1/WebKitNetworkProcess ./lib/x86_64-linux-gnu/webkit2gtk-4.1/
ln -sf /usr/lib/webkit2gtk-4.1/WebKitWebProcess ./lib/x86_64-linux-gnu/webkit2gtk-4.1/
ln -sf /usr/lib/webkit2gtk-4.1/injected-bundle/libwebkit2gtkinjectedbundle.so ./lib/x86_64-linux-gnu/webkit2gtk-4.1/injected-bundle/

After applying these symlinks, the application works perfectly by running the binary directly with specific compatibility flags:

`GDK_BACKEND=x11 ./usr/bin/Quantframe`

This confirms that the app is viable on Arch, but the AppImage packaging needs to be updated to handle non-Debian path resolutions and modern EGL/Wayland negotiation.

Please take this with caution. As I mentioned before, I am not a developer and lack the formal technical background to definitively confirm this is the core issue, but I hope these findings provide a helpful starting point for others and the maintainers.

[Katze719]

RPM package works though (for me at least), its just the AppImage