Electron installer fails at libnss3.so

[ShaneDugas]

error while loading shared libraries: libnss3.so: cannot open shared object file: No such file or directory

---

---

PAI Installer v3.0 fails on RHEL/CentOS 9 — missing libnss3.so

Environment:

• OS: RHEL/CentOS 9 (Linux 5.14.0-611.24.1.el9_7.x86_64)
• Arch: x86_64
• Bun: v1.3.9
• Git: 2.47.3
• Claude Code: installed
• PAI Installer: v3.0
• Electron: (bundled in PAI-Install/electron/node_modules/electron/)

Preflight checks all pass:

• curl, Git, Bun, Claude Code all detected successfully

Error:

pai-installer@3.0.0 start
electron .

~/.claude/PAI-Install/electron/node_modules/electron/dist/electron: error while loading shared libraries: libnss3.so: cannot open shared object file: No such file or directory

Exit code: 127

Root cause:
The Electron GUI requires libnss3.so (from the NSS libraries), which is not installed on the system. On RHEL/EL9 this is provided by the nss package. Electron also commonly requires libatk-1.0,
libatk-bridge-2.0, libcups, libdrm, libgbm, libgtk-3, libxkbcommon, and others.

Suggested fix options:

1. Add a preflight check for Electron's required system libraries and surface a clear error message listing which packages to install
2. Provide a headless/CLI fallback for systems without a full desktop library stack
3. Document the required system packages per distro (e.g., sudo dnf install nss atk at-spi2-atk cups-libs libdrm mesa-libgbm gtk3 libxkbcommon for RHEL 9)

[ShaneDugas]

---

PAI Installer v3.0 — Electron GUI fails on headless Linux (missing GUI libraries)

Environment

┌───────────────┬────────────────────────────────────────┐
│ Component │ Value │
├───────────────┼────────────────────────────────────────┤
│ OS │ Rocky Linux 9.7 (Blue Onyx) │
├───────────────┼────────────────────────────────────────┤
│ Kernel │ 5.14.0-611.24.1.el9_7.x86_64 │
├───────────────┼────────────────────────────────────────┤
│ Arch │ x86_64 │
├───────────────┼────────────────────────────────────────┤
│ Session │ SSH (headless, no X11/Wayland display) │
├───────────────┼────────────────────────────────────────┤
│ Bun │ v1.3.9 │
├───────────────┼────────────────────────────────────────┤
│ Node │ v16.20.2 │
├───────────────┼────────────────────────────────────────┤
│ PAI Installer │ v3.0 │
└───────────────┴────────────────────────────────────────┘

What happened

The bootstrap script (install.sh) runs successfully through all prerequisite checks (curl, git, bun,
claude), then fails at the final step when it launches the Electron GUI via bun run main.ts --mode
gui:

~/.claude/PAI-Install/electron/node_modules/electron/dist/electron: error while loading shared
libraries: libatk-1.0.so.0: cannot open shared object file: No such file or directory

Exit code: 127

Root cause

Two compounding issues:

1. Missing GUI libraries — The Electron binary requires 17 shared libraries that are not installed on
   a minimal/server Rocky Linux 9 installation:
   - libatk-1.0.so.0, libatk-bridge-2.0.so.0, libatspi.so.0
   - libgtk-3.so.0, libgbm.so.1
   - libpango-1.0.so.0, libcairo.so.2
   - libcups.so.2
   - libX11.so.6, libXcomposite.so.1, libXdamage.so.1, libXext.so.6, libXfixes.so.3, libXrandr.so.2,
   libxcb.so.1, libxkbcommon.so.0
   - libasound.so.2
2. No display server — The system is accessed via SSH with no DISPLAY or WAYLAND_DISPLAY set
   (XDG_SESSION_TYPE=tty). Even if the libraries were installed, Electron would fail without a display
   (or --no-sandbox + xvfb).

Expected behavior

The installer should either:

• Detect headless/SSH environments and fall back to a TUI/CLI mode (the script already accepts --mode
  gui, implying other modes may exist)
• Print a clear error message explaining that a display server is required, with instructions for
  headless users
• Document the required system packages for Linux GUI mode

Suggested fix

Before launching Electron, check for display

if [[ -z "${DISPLAY:-}" && -z "${WAYLAND_DISPLAY:-}" ]]; then
warn "No display server detected (headless/SSH session)."
info "Falling back to CLI mode..."
exec bun run "$INSTALLER_DIR/main.ts" --mode cli
fi

And/or document the required packages for RHEL/Rocky 9:

sudo dnf install -y atk at-spi2-atk cups-libs gtk3 pango cairo
libX11 libXcomposite libXdamage libXext libXfixes libXrandr
libxcb libxkbcommon mesa-libgbm alsa-lib

Steps to reproduce

1. SSH into a minimal Rocky Linux 9 server (no desktop environment)
2. Install PAI prerequisites (bun, curl, git, claude)
3. Run ./PAI-Install/install.sh
4. Observe the libatk-1.0.so.0 error at launch

---

[kaimagnus]

Closing — moot with #755 (headless/SSH auto-detection in v4.0.2). The installer now automatically detects headless environments and falls back to CLI mode, bypassing the Electron/libnss3 issue entirely.