From 6c1f167f15902039e1a73ebdeca2a12406a337c5 Mon Sep 17 00:00:00 2001
From: Samuel James <143277412+SamuelSJames@users.noreply.github.com>
Date: Mon, 22 Jun 2026 15:01:22 -0400
Subject: [PATCH] Document xrdp blank-screen fix #2: disable xfwm4 compositing
 on virtio GPU (#43)

Even with XFCE running, the screen stayed blank because xfwm4's GPU compositor
fails on the Virtio GPU (no GL driver): "Another compositing manager is running",
"failed to load driver: virtio_gpu". Fixed by disabling xfwm4 compositing via
xfconf and forcing LIBGL_ALWAYS_SOFTWARE for the RDP user. Verified a fresh
session renders cleanly through guacd.

Co-authored-by: Samuel James <ssamjame@amazon.com>
Co-authored-by: Kiro <noreply@kiro.dev>
---
 docs/rdp-debug-handoff.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/docs/rdp-debug-handoff.md b/docs/rdp-debug-handoff.md
index 03d04e8..4d23ca9 100644
--- a/docs/rdp-debug-handoff.md
+++ b/docs/rdp-debug-handoff.md
@@ -58,6 +58,30 @@ plus the alternative considered:
   sudo systemctl restart xrdp-sesman xrdp
   ```
   Verified: `xfce4-session` + `xfwm4` stay running and guacd streams sustained desktop frames.
+
+  **Second gotcha (still blank even with XFCE running):** if all XFCE processes
+  (`xfce4-session`/`xfwm4`/`xfdesktop`) are alive but the screen is still blank, it's xfwm4's
+  **GPU compositor** failing on a GPU with no GL driver. Tell-tale lines in `~/.xsession-errors`:
+  `xfwm4-WARNING: Another compositing manager is running on screen 0`,
+  `glx: failed to create dri3 screen`, `failed to load driver: virtio_gpu`. Fix — disable xfwm4
+  compositing and force software GL for the RDP user, then reconnect (kill the stale session
+  first so it respawns):
+  ```bash
+  mkdir -p ~/.config/xfce4/xfconf/xfce-perchannel-xml
+  cat > ~/.config/xfce4/xfconf/xfce-perchannel-xml/xfwm4.xml <<'XML'
+  <?xml version="1.0" encoding="UTF-8"?>
+  <channel name="xfwm4" version="1.0">
+    <property name="general" type="empty">
+      <property name="use_compositing" type="bool" value="false"/>
+    </property>
+  </channel>
+  XML
+  # force llvmpipe so any GL app falls back to software instead of failing on virtio_gpu
+  sed -i '1a export LIBGL_ALWAYS_SOFTWARE=1' ~/.xsession
+  sudo pkill -u "$USER" xfce4-session; sudo pkill -u "$USER" Xvnc   # then reconnect
+  ```
+  Verified: fresh session has zero "Another compositing manager" errors and guacd streams a
+  clean rendering desktop. This is the likely culprit on any VM with a Virtio/virtual GPU.
 - **Alternative (infra, affects everyone): a custom guacd build with FreeRDP 3.** Not worth it
   yet — it's a 30+ min from-source build to maintain in `docker-compose.yml`, for one upstream
   gap that Apache will eventually close. Revisit if/when `guacamole/guacd` ships FreeRDP 3.