From 668da772418b69eba93f2c32ea187acda3fe7d94 Mon Sep 17 00:00:00 2001 From: Johannes Date: Wed, 22 Jul 2026 13:09:22 -0400 Subject: [PATCH] docs(technical.browser): GPU must run out-of-process (SwiftShader int3 crash, #97) Document the ~hourly Linux crash: SwiftShader compositor int3 is fatal only under --in-process-gpu. Add the load-bearing rule (never in-process-gpu), the HIVEOPS_GPU override, diagnostics, and the not-an-OOM distinction. Co-Authored-By: Claude Opus 4.8 --- .../content/technical/browser/gotchas.md | 21 +++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/backend/src/main/resources/content/technical/browser/gotchas.md b/backend/src/main/resources/content/technical/browser/gotchas.md index 28c4eec..96c00ac 100644 --- a/backend/src/main/resources/content/technical/browser/gotchas.md +++ b/backend/src/main/resources/content/technical/browser/gotchas.md @@ -27,6 +27,27 @@ self-prompt**, for any user/role — the fix (remove the beta channel, remove th Bug introduced in `bca8f60` (2026-06-30, ~10 min before the 2.4.7 build); fixed in `8a5cd3a` + `cfbae6a`. +## Linux: the GPU must run OUT-OF-PROCESS (SwiftShader compositor `int3`) + +On Linux the app forces **SwiftShader** software rendering (`use-gl=swiftshader` + `disable-gpu`) to +dodge hardware-GPU driver instability on AMD **gfx1150** and other new GPUs (the old exit-133 / +SIGTRAP renderer crash). But SwiftShader's *own* compositor periodically aborts under sustained use — +kernel log `traps: Compositor[...] trap int3 ... in hiveops-browser`. + +**The load-bearing rule: never `--in-process-gpu`.** With the GPU in-process, that compositor abort +kills the **whole app** — symptom: *"the browser closes every ~hour, even sitting idle overnight."* +Running the GPU out-of-process makes the same abort a recoverable GPU-process restart instead. Fixed +in **#97 / 2.5.0** by dropping `--in-process-gpu` and `--disable-gpu-sandbox` (SwiftShader kept). + +- **Override:** `HIVEOPS_GPU=hardware` uses the real GPU instead of SwiftShader (worth retrying as + Mesa stabilises gfx1150); unset / anything else keeps the safe SwiftShader default. +- **Diagnose:** `journalctl | grep 'Compositor.*trap int3'` (crash history), and confirm a + `--type=gpu-process` child exists (`ps -C hiveops-browser -o args | grep gpu-process`) — present = + out-of-process = good; absent = the fatal in-process config regressed. +- Not to be confused with an OOM: these crashes happen with plenty of free RAM and no oom-killer + events, and leave orphaned `~/.config/hiveops-browser/.org.chromium.Chromium.*` temp files (one per + unclean exit). + ## "Self signed certificate" on login = DNS, not code If the browser errors with a self-signed-certificate message, it's almost always a **DNS / `/etc/hosts`