[BUG] [Linux] Recording overlay flickers with WebKitGTK 2.54 when DMA-BUF rendering is forcibly disabled

Open

Before You Submit

I searched existing issues for WebKitGTK 2.54, DMA-BUF, and overlay flickering, and did not find a matching report. #1806 concerns a different main-window layout problem.

Bug Description

The recording overlay appears as a tiny white rectangle containing a pink dot, with visible flickering, instead of the complete recording indicator. Dictation itself still works.

I noticed this after rebooting. Package history shows that WebKitGTK was upgraded from 2.52.5 to 2.54.0 on September 25, 2026. I have not performed a controlled comparison with the previous WebKitGTK version.

Steps to reproduce:

Run Handy 0.9.7 on the system described below.
Enable the recording overlay, with style Live and position Bottom.
Start dictation using handy --toggle-transcription.

Expected behavior:

The complete recording indicator remains visible and stable.

Actual behavior:

Only small animated portions remain visible, usually the pink dot, while the rest disappears.

Diagnostic findings:

The GTK window and WebView are correctly sized at 256 × 50 pixels. The indicator’s DOM dimensions are 174 × 42 pixels.
A WebKit page snapshot contains the complete indicator, while the GTK widget snapshot and screen capture show the broken output.
Handy unconditionally sets WEBKIT_DISABLE_DMABUF_RENDERER=1 in src-tauri/src/main.rs, overriding an externally supplied value of 0.
A temporary local LD_PRELOAD shim that prevents this override restores the complete indicator. This was verified across repeated openings.

Allowing users to explicitly override this environment variable could provide a workaround. The exact underlying WebKit defect remains unconfirmed; no standalone WebKit reproducer has been tested.

System Information

App Version:

Handy 0.9.7, native RPM (handy-0.9.7-1.x86_64).

Operating System:

Fedora Linux 44 Sway Spin, currently running Niri 26.04 on Wayland.

CPU:

AMD Ryzen 5 PRO 7540U.

GPU:

AMD Radeon 740M integrated graphics, Phoenix.

Relevant libraries:

WebKitGTK: 2.54.0-2.fc44, API 4.1
GTK: 3.24.52
gtk-layer-shell: 0.10.0

Logs

The following excerpts come from a temporary local diagnostic probe, not standard Handy logs.

Without the workaround:

HANDY_PROBE widget GtkApplicationWindow x=0 y=0 width=256 height=50 mapped=1
HANDY_PROBE widget WebKitWebView x=0 y=0 width=256 height=50 mapped=1
HANDY_PROBE hardware-policy 2

With the workaround:

HANDY_PROBE overriding forced DMABUF disable
HANDY_PROBE hardware-policy 1

Policy 2 corresponds to NEVER; policy 1 corresponds to ALWAYS.

Activity

sbrehme22d ago

Same here on a different compositor and GPU, so it doesn't look Niri/AMD-specific:

Fedora 44, KDE Plasma 6.7.3 (Wayland/KWin)
Intel Raptor Lake UHD (hybrid laptop with an NVIDIA dGPU; Handy's UI runs on the Intel iGPU)
webkit2gtk4.1-2.54.1-1.fc44, Handy 0.9.8 (RPM), overlay style Live, position Bottom

Symptom is identical: only the regions that changed in the last few milliseconds are drawn, everything static (background, already-shown text) blinks out, so the overlay flickers constantly.

Confirming your analysis: setting WEBKIT_DISABLE_DMABUF_RENDERER (or WEBKIT_DISABLE_COMPOSITING_MODE) from outside has no effect, because main.rs overwrites it. An LD_PRELOAD shim that drops exactly that one setenv makes the overlay stable (after a single flicker right at the start), across menu launch, global shortcut and autostart:

#define _GNU_SOURCE
#include <dlfcn.h>
#include <string.h>

int setenv(const char *name, const char *value, int overwrite) {
    static int (*real_setenv)(const char *, const char *, int);
    if (!real_setenv)
        real_setenv = (int (*)(const char *, const char *, int))dlsym(RTLD_NEXT, "setenv");
    if (name && strcmp(name, "WEBKIT_DISABLE_DMABUF_RENDERER") == 0)
        return 0;
    return real_setenv(name, value, overwrite);
}

gcc -shared -fPIC -O2 -o libhandy-keep-dmabuf.so shim.c -ldl, then LD_PRELOAD=/path/to/libhandy-keep-dmabuf.so handy. Note that for autostart on Plasma, Handy rewrites ~/.config/autostart/Handy.desktop with Exec=/usr/bin/handy on every start, so the env has to be injected elsewhere (I used a systemd drop-in for app-Handy@autostart.service).

+1 for only setting the variable when it isn't already set (if std::env::var_os("WEBKIT_DISABLE_DMABUF_RENDERER").is_none()), the same way VK_LOADER_LAYERS_DISABLE is handled on Windows. That would keep the crash protection from tauri-apps/tauri#9394 as the default while letting affected users opt out with WEBKIT_DISABLE_DMABUF_RENDERER=0.

christophergoltz22d ago

Same issue

jestarray21d ago

I have this same issue on Arch Linux on Sway(wayland)

cjpais21d ago

folks here @jestarray @sbrehme @christophergoltz @lpoirothattermann can you try this build https://github.com/cjpais/Handy/actions/runs/37897722989

run handy with WEBKIT_DISABLE_DMABUF_RENDERER=0 handy it should work now as @sbrehme suggested

dobegor20d ago

@cjpais hey, I've just encountered this problem after an update and found this github issue. I've tried the appimage build you've linked and I'm happy to report that it indeed works and no more flickering!

Handy: 0.9.8 (handy-bin via AUR) WebKitGTK: 2.54.1 Tested the patched AppImage from PR #2249 with WEBKIT_DISABLE_DMABUF_RENDERER=0.

cjpais20d ago

@dobegor thanks for the confirmation, just merged it, next release will have the fix

not ideal but at least its documented here and in the readme

christophergoltz15d ago

Confirmed on Arch (KDE Plasma 6, Wayland, RX 9070 XT, WebKitGTK 2.54.1): the main build (14ae9c6b) with WEBKIT_DISABLE_DMABUF_RENDERER=0 fixes the overlay flicker just like the LD_PRELOAD shim did, apart from the same single short flicker right after it appears. Thanks!

KidesLeo12d ago

NVIDIA data point for the WEBKIT_DISABLE_DMABUF_RENDERER=0 workaround: on NVIDIA it crashes Handy unless explicit sync is also disabled.

Setup: CachyOS, KDE Plasma 6.8.0 (Wayland), RTX 4080 Laptop in dGPU-only mode (no iGPU exposed), nvidia-open 615.78.08, webkit2gtk-4.1 2.54.1, gtk3 3.24.52, gtk-layer-shell 0.10.1, Handy 0.9.8 (AUR), overlay style Live.

What happened: after WebKitGTK went from 2.52.6 to 2.54.1 on 10-07, the overlay started flickering. Most of the time I only saw a small dark square around the pulsing pink dot, and every so often the whole pill flashed in. The main settings window looked fine the whole time.

I first tried the usual WebKit env vars (WEBKIT_DISABLE_COMPOSITING_MODE=1, WEBKIT_SKIA_ENABLE_CPU_RENDERING=1) and nothing changed. Then I found this issue and realised 0.9.8 overwrites WEBKIT_DISABLE_DMABUF_RENDERER, so anything I passed for that one never reached WebKit.

To measure it instead of eyeballing it, I put a fullscreen solid-colour window behind the overlay, started a recording, took 16 screenshots and counted the frames where the full pill was drawn. Then I:

Rolled WebKitGTK back to 2.52.6 from the pacman cache. The overlay was perfect, 16/16. Went back to 2.54.1 and it was broken again.
Tried WEBKIT_USE_SKIA_FOR_COMPOSITION=0, the workaround from WebKit bug 327524. Still broken.
Used @sbrehme's setenv LD_PRELOAD shim to get the #2249 behaviour on 0.9.8, so the DMA-BUF renderer stays on. Handy died about 6 s after starting, exactly when the overlay appeared:
```
Gdk-Message: Error 71 (Protocol error) dispatching to Wayland display.
```
I assume this is the NVIDIA crash the forced =1 was protecting against (tauri-apps/tauri#9394).
Kept the shim and added __NV_DISABLE_EXPLICIT_SYNC=1. The overlay rendered perfectly, Handy survived repeated record/stop cycles, and the WebKitWebProcess now loads libEGL_nvidia, so it is GPU-rendered instead of falling back to CPU. The main window is fine too.

Config	Full-pill frames	Notes
WebKitGTK 2.54.1, Handy defaults (DMA-BUF forced off)	0-1 / 16	only a square around the pulsing dot is drawn
WebKitGTK 2.52.6, Handy defaults	16 / 16	regression is in 2.54
2.54.1 + `WEBKIT_USE_SKIA_FOR_COMPOSITION=0`	0 / 16	workaround from WebKit bug 327524 does not help here
2.54.1 + DMA-BUF renderer on	n/a	Handy exits as the overlay appears, `Error 71 (Protocol error)`
2.54.1 + DMA-BUF renderer on + `__NV_DISABLE_EXPLICIT_SYNC=1`	16 / 16	stable; WebKitWebProcess loads `libEGL_nvidia`

So for NVIDIA users the README workaround probably needs to be WEBKIT_DISABLE_DMABUF_RENDERER=0 __NV_DISABLE_EXPLICIT_SYNC=1 handy, otherwise they trade the flicker for the original tauri-apps/tauri#9394-style crash.