From ddbd0fcbe5436826d2ca1aea6f5e8d3104d1d08c Mon Sep 17 00:00:00 2001 From: Aqil Aziz Date: Fri, 22 May 2026 18:24:02 +0700 Subject: [PATCH] docs(linux): add AppImage failure notes (#2391) --- gitbooks/features/platform.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/gitbooks/features/platform.md b/gitbooks/features/platform.md index ffe014706..fd9d515da 100644 --- a/gitbooks/features/platform.md +++ b/gitbooks/features/platform.md @@ -19,6 +19,23 @@ OpenHuman is a native desktop application, not a browser extension, not an Elect | **Windows** | x64, ARM64 | `.msi` installer | | **Linux** | x64 | AppImage, `.deb` | +### Linux AppImage notes + +The Linux AppImage is built for x64 desktops and is the default asset selected +by the curl installer. On newer distributions, especially builds that tighten +unprivileged user namespaces or AppArmor defaults, AppImage startup can fail +before OpenHuman reaches its own crash reporter. Known symptoms include: + +- `unshare: write failed /proc/self/uid_map: Operation not permitted` +- `Interpreter not found!` +- `cannot execute binary file` + +When that happens, prefer the `.deb` package on Debian/Ubuntu systems. For +Fedora, openSUSE, and other non-Debian distributions, include the distro +version, kernel version, GPU/driver stack, and the exact AppImage filename when +reporting the issue so maintainers can distinguish host restrictions from a +badly packaged AppImage runtime. + *** ## Why native matters