|
| 1 | +# Linux Rendering Troubleshooting |
| 2 | + |
| 3 | +This guide covers the most common rendering failures on Linux and how to resolve them. It covers both the AppImage distribution and native package installs (`deb`, `rpm`). |
| 4 | + |
| 5 | +## Symptoms and fixes at a glance |
| 6 | + |
| 7 | +| Symptom | Likely cause | Fix | |
| 8 | +|---------|-------------|-----| |
| 9 | +| Blank or transparent window, then `SIGABRT` with `colrv1_configure_skpaint` in the output | COLRv1 color emoji font (AppImage only) | Upgrade to the latest AppImage (v0.5.2+) | |
| 10 | +| Blank window on startup, no crash output | dmabuf renderer incompatibility (NVIDIA or AppImage) | `WEBKIT_DISABLE_DMABUF_RENDERER=1 ./Buzz.AppImage` or `--safe-rendering` | |
| 11 | +| Blank window on any hardware, no crash output | Unknown GPU/driver combination | `--safe-rendering` flag (see below) | |
| 12 | + |
| 13 | +--- |
| 14 | + |
| 15 | +## Crash: `colrv1_configure_skpaint` assertion abort (AppImage) |
| 16 | + |
| 17 | +**Affected distributions:** Fedora 40+ and any distro shipping Google's Noto Color Emoji in COLRv1 format (`Noto-COLRv1.ttf`). Issues [#2548](https://github.com/block/buzz/issues/2548), [#2982](https://github.com/block/buzz/issues/2982). |
| 18 | + |
| 19 | +**Symptom:** Buzz starts, the window appears briefly (or stays blank), then the process aborts with output like: |
| 20 | + |
| 21 | +``` |
| 22 | +././/include/c++/12/bits/stl_vector.h:1123: ... colrv1_configure_skpaint ...: |
| 23 | +Assertion '__n < this->size()' failed. |
| 24 | +``` |
| 25 | + |
| 26 | +**Root cause:** The AppImage bundles WebKitGTK compiled against FreeType 2.11.1 (Ubuntu 22.04's version), but `libfreetype.so.6` is not bundled — WebKit loads the host's FreeType at runtime instead. FreeType 2.13.0 (2023-02-09) added a field to `FT_ColorStopIterator`, growing the struct from 16 to 20 bytes. On Fedora 40+ hosts (FreeType ≥ 2.13), the struct-layout mismatch corrupts color-stop index arithmetic inside Skia's COLRv1 renderer, producing the assertion abort. |
| 27 | + |
| 28 | +**Fix:** Upgrade to the latest AppImage (v0.5.2+). The build container was bumped to `ubuntu:24.04` ([#3602](https://github.com/block/buzz/pull/3602)), which ships FreeType 2.13.2. The compiled layout now matches every crash-affected host (FreeType ≥ 2.13), eliminating the ABI mismatch. |
| 29 | + |
| 30 | +**AppImage glibc floor (v0.5.2+):** The `ubuntu:24.04` build raises the AppImage's minimum glibc requirement: |
| 31 | + |
| 32 | +| AppImage version | glibc floor | Oldest supported AppImage distro | |
| 33 | +|---|---|---| |
| 34 | +| v0.5.1 and earlier | 2.35 | Ubuntu 22.04 LTS, Debian 12 | |
| 35 | +| v0.5.2+ | 2.39 | Ubuntu 24.04 LTS, Fedora 40+ | |
| 36 | + |
| 37 | +If you are on **Ubuntu 22.04 LTS or Debian 12**, upgrade to the latest **`.deb`/`.rpm`** package instead — native packages use the system WebKit and are unaffected by this change. |
| 38 | + |
| 39 | +**Workaround (before upgrading):** Add a fontconfig override that removes color-format fonts from Buzz's view: |
| 40 | + |
| 41 | +```bash |
| 42 | +mkdir -p ~/.config/buzz-fontconfig |
| 43 | +cat > ~/.config/buzz-fontconfig/fonts.conf <<'XML' |
| 44 | +<?xml version="1.0"?> |
| 45 | +<!DOCTYPE fontconfig SYSTEM "fonts.dtd"> |
| 46 | +<fontconfig> |
| 47 | + <include ignore_missing="yes">/etc/fonts/fonts.conf</include> |
| 48 | + <selectfont> |
| 49 | + <rejectfont> |
| 50 | + <pattern> |
| 51 | + <patelt name="color"><bool>true</bool></patelt> |
| 52 | + </pattern> |
| 53 | + </rejectfont> |
| 54 | + </selectfont> |
| 55 | +</fontconfig> |
| 56 | +XML |
| 57 | +FONTCONFIG_FILE=~/.config/buzz-fontconfig/fonts.conf ./Buzz_*.AppImage |
| 58 | +``` |
| 59 | + |
| 60 | +**Native packages (`deb`/`rpm`):** The COLRv1 crash ([#2548](https://github.com/block/buzz/issues/2548), [#2982](https://github.com/block/buzz/issues/2982)) is AppImage-only — native packages use the system WebKit, which has a consistent FreeType ABI, and are not affected. |
| 61 | + |
| 62 | +--- |
| 63 | + |
| 64 | +## Blank window on startup (no crash): dmabuf renderer |
| 65 | + |
| 66 | +**Affected hardware:** NVIDIA GPUs (proprietary and nouveau drivers) and AppImage installs on any GPU. Issue [#2338](https://github.com/block/buzz/issues/2338). |
| 67 | + |
| 68 | +**Symptom:** Buzz launches without any crash or assertion output, but the window is blank or invisible. The process is running (`ps aux | grep buzz`), but nothing renders. |
| 69 | + |
| 70 | +**Root cause:** WebKitGTK's dmabuf zero-copy buffer path is incompatible with some GPU/driver/compositor combinations. The WebKit child process silently fails to paint. |
| 71 | + |
| 72 | +**Fix (shipped automatically starting with the first release containing [#3271](https://github.com/block/buzz/pull/3271) (v0.5.1)):** Buzz sets `WEBKIT_DISABLE_DMABUF_RENDERER=1` automatically before WebKit initializes when it detects an NVIDIA GPU (`/sys/class/drm` vendor ID `0x10de`) or when running as an AppImage. This restores a slightly slower shared-memory rendering path that works universally. |
| 73 | + |
| 74 | +**If automatic detection doesn't help (`--safe-rendering`):** Pass `--safe-rendering` to force both `WEBKIT_DISABLE_DMABUF_RENDERER=1` and `WEBKIT_DISABLE_COMPOSITING_MODE=1` for that launch: |
| 75 | + |
| 76 | +```bash |
| 77 | +./Buzz_*.AppImage --safe-rendering |
| 78 | +# or for a native install: |
| 79 | +buzz-desktop --safe-rendering |
| 80 | +``` |
| 81 | + |
| 82 | +`--safe-rendering` is a per-launch flag — it is not remembered between runs. If it fixes your issue, you can make it permanent by setting the env vars yourself: |
| 83 | + |
| 84 | +```bash |
| 85 | +# ~/.bashrc or ~/.profile |
| 86 | +export WEBKIT_DISABLE_DMABUF_RENDERER=1 |
| 87 | +``` |
| 88 | + |
| 89 | +**Conflict detection:** If you set a WebKit variable in your environment and also pass `--safe-rendering`, Buzz will refuse to start and print exactly which variable conflicts. Unset the conflicting variable or drop the flag. |
| 90 | + |
| 91 | +--- |
| 92 | + |
| 93 | +## AMD RDNA4 / transparent window |
| 94 | + |
| 95 | +**Affected hardware:** AMD RDNA4 GPUs (RX 9000 series) with the `radv` driver. Issue [#2643](https://github.com/block/buzz/issues/2643). |
| 96 | + |
| 97 | +**Symptom:** The Buzz window is transparent or renders with graphical corruption on AMD RDNA4 hardware. |
| 98 | + |
| 99 | +**Workaround (verified by reporter):** Set these three variables before launching Buzz: |
| 100 | + |
| 101 | +```bash |
| 102 | +export GDK_BACKEND=x11 |
| 103 | +export WEBKIT_DISABLE_DMABUF_RENDERER=1 |
| 104 | +export WEBKIT_SKIA_ENABLE_CPU_RENDERING=1 |
| 105 | +./Buzz_*.AppImage |
| 106 | +# or for native: |
| 107 | +buzz-desktop |
| 108 | +``` |
| 109 | + |
| 110 | +- `WEBKIT_SKIA_ENABLE_CPU_RENDERING=1` forces Skia to use CPU rendering, bypassing the RDNA4 Skia/radv paint failure. |
| 111 | +- `GDK_BACKEND=x11` avoids the blank window that appears when running under a Plasma-Wayland compositor. |
| 112 | +- `WEBKIT_DISABLE_DMABUF_RENDERER=1` prevents post-first-paint transparency from the dmabuf renderer. |
| 113 | + |
| 114 | +A dedicated fix for RDNA4 detection is being tracked in [#2643](https://github.com/block/buzz/issues/2643). |
| 115 | + |
| 116 | +--- |
| 117 | + |
| 118 | +## Diagnosing an unrecognised crash |
| 119 | + |
| 120 | +If none of the above match your situation: |
| 121 | + |
| 122 | +1. Run Buzz from a terminal and capture the output: |
| 123 | + ```bash |
| 124 | + ./Buzz_*.AppImage 2>&1 | tee buzz-crash.log |
| 125 | + ``` |
| 126 | + |
| 127 | +2. Check for a core dump: |
| 128 | + ```bash |
| 129 | + coredumpctl list | tail |
| 130 | + coredumpctl info <PID> |
| 131 | + ``` |
| 132 | + |
| 133 | +3. Try `--safe-rendering` first — if it resolves the issue, it's a WebKit rendering incompatibility and the crash log will help narrow down which driver is involved. |
| 134 | + |
| 135 | +4. File a [new issue](https://github.com/block/buzz/issues/new) with your distro, GPU, driver version, and the terminal output. |
0 commit comments