Skip to content

Linux AppImage: bundled libwayland-client prevents host Mesa EGL initialization #112

Closed

Description

@pablousx

Stroke's AppImage WebKitWebProcess aborts during EGL initialization on an
Arch/Omarchy host. The host graphics stack works normally. The AppImage's
bundled libwayland-client.so.0 shadows the host copy and prevents the host
Mesa EGL vendor library from loading.

Confirmed loader error:

/usr/lib/libEGL_mesa.so.0: undefined symbol: wl_fixes_interface

WebKit's abort call site references:

Could not create surfaceless EGL display: %s. Aborting...

Environment

  • Arch Linux / Omarchy; kernel 7.2.8-9-omarchy
  • AMD Radeon RX 6600; Mesa 26.2.5-1
  • Wayland 1.26.0-1; libglvnd 1.7.0-3
  • Hyprland session; AppImage startup hook forces GDK_BACKEND=x11
  • Older installed Stroke AppImage, exact application version unconfirmed
  • SHA-256: cc08e110f801968a543bec9e4f985cff6b586cdef1b83f63b5c2959e15dcfa42
  • A newly downloaded Stroke 2.3.0 AppImage also produced the same WebKit
    abort call site. Detailed library isolation below used the older artifact.

Reproduction and controlled diagnosis

  1. Launch the unmodified AppImage on this host. WebKitWebProcess aborts.
  2. Run the host eglinfo -B: successful EGL initialization, including the
    surfaceless platform, using Mesa and the AMD GPU.
  3. Extract the AppImage to a temporary directory. Run the host eglinfo -B
    with LD_LIBRARY_PATH pointing to the extracted usr/lib directory:
    EGL initialization fails on GBM, Wayland, X11 and surfaceless platforms.
  4. Set LD_DEBUG=libs,versions and select the Mesa vendor with
    __EGL_VENDOR_LIBRARY_FILENAMES=/usr/share/glvnd/egl_vendor.d/50_mesa.json.
    The loader reports the missing wl_fixes_interface symbol shown above.
  5. Remove only libwayland-client.so.0 from the TEMPORARY extracted directory
    and repeat the probe. EGL initialization succeeds on all those platforms.
    The installed AppImage was not modified for this test.

Local workaround validation

A launcher setting LD_PRELOAD=/usr/lib/libwayland-client.so.0 before executing
the older AppImage successfully rendered Stroke's UI. The test used disposable
XDG config/data/cache/state directories and was run outside the sandbox.
Stroke remained running for the 12-second observation interval with empty
captured startup output. Its rendered UI displayed the expired-trial/license
screen. Database functionality was not tested. The test instance was closed.
This absolute library path is host-specific and is not proposed as an upstream
implementation.

Proposed packaging fix

Exclude libwayland-client.so.0 during AppImage dependency collection, before
the final image is packed, so the host Mesa library uses the matching host
Wayland client library. Ensure plugins do not reintroduce it. Add an artifact
check covering usr/lib and architecture-specific library directories.

Keep this change focused: excluding other libraries has not been established
as necessary by these tests. If supported systems can lack a Wayland client
library, document that dependency or evaluate a host-first fallback outside
the default library search path.

Suggested acceptance checks

  • No bundled libwayland-client.so.0 (including versioned copies/symlinks) in
    the generated AppImage's active library search directories.
  • Launch and verify rendered UI on current Mesa without LD_PRELOAD.
  • Test X11 and Wayland sessions and the oldest supported distribution.
  • No EGL initialization abort or new WebKitWebProcess coredump.

Upstream precedent

The AppImage community excludelist already excludes libwayland-client.so.0
because bundling it can break newer Mesa:
https://github.com/AppImageCommunity/pkg2appimage/blob/master/excludelist
AppImageCommunity/pkg2appimage#559

Scope and limitations

This establishes a reproducible AppImage/host library conflict; it does not
establish an Omarchy defect or an NVIDIA driver defect. Some NVIDIA libraries
were loaded in the crash, but successful host EGL rendering uses AMD/Mesa.
The application build pipeline was not available for inspection, and no rebuilt
release artifact has been tested. No core dump or private database content is
included.

Prepared with Codex (GPT-6).

Activity

  1. added
    bugSomething isn't working
    linuxLinux builds and packaging
    in progressSomeone is working on this
    release:patchDefault for PRs into nightly: next patch (.9 rolls to the next minor). On master: hotfix release
    size:SLines changed
    on Nov 14, 2026
  2. self-assigned this
    on Nov 14, 2026
  3. broisnees commented on Nov 17, 2026

    @broisnees
    Collaborator

    Thanks a lot for this report, @pablousx. The library isolation and the LD_PRELOAD check made the cause easy to pin down.

    The fix is in: the AppImage no longer bundles libwayland-client, so it uses your system's copy and Mesa's EGL loads normally. I confirmed it on Arch (Omarchy, Hyprland, AMD, Mesa 26.1): the AppImage starts and draws with no workaround, under both XWayland and native Wayland, with no EGL abort and no crash dumps.

    It's in Stroke Nightly today, and it ships to everyone in Stroke v3. If you'd like it sooner, the Nightly installs alongside Stroke: https://github.com/stroke-app/stroke/releases/tag/nightly. To try native Wayland, start the AppImage with STROKE_WAYLAND=1.

    Thanks again for taking the time.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

bugSomething isn't workingin progressSomeone is working on thislinuxLinux builds and packagingrelease:patchDefault for PRs into nightly: next patch (.9 rolls to the next minor). On master: hotfix releasesize:SLines changed

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions