VNC Desktop Black Screen Fix (GDK_BACKEND=x11)

Problem

VNC desktop via gui.meiyoucheveux.com shows a black screen despite xfce4-session, xfce4-panel, and Xtigervnc all running correctly on display :2. The missing component is xfdesktop4 — the desktop background manager — which repeatedly crashes on startup.

Root Cause

xfdesktop4 loads libgtk-layer-shell.so.0 (Wayland layer-shell protocol library) on the X11 VNC display. Since no Wayland compositor exists on the Xvnc display, the library triggers:

WARNING: It appears your Wayland compositor does not support the Layer Shell protocol
CRITICAL: Your compositor must support the zwlr_layer_shell_v1 protocol

This causes xfdesktop to exit with code 1, leaving a black desktop background.

Why XDG_SESSION_TYPE=x11 Wasn’t Enough

The xstartup already set unset WAYLAND_DISPLAY and export XDG_SESSION_TYPE=x11, which correctly identifies the session type. However, GTK 3 still dynamically loads libgtk-layer-shell as a GTK module even when WAYLAND_DISPLAY is unset — it checks for the library at runtime, not at session-initialization time.

Solution

Add export GDK_BACKEND=x11 to the VNC startup script (~/.config/tigervnc/xstartup). This forces all GTK applications to use the X11 backend exclusively, preventing libgtk-layer-shell from being loaded.

File Changed

~/.config/tigervnc/xstartup  (also accessible as ~/.vnc/xstartup — symlinked)

Diff

 #!/bin/bash
 unset WAYLAND_DISPLAY
+# Force GTK apps (esp. xfdesktop) onto the X11 backend. Without this, versioned
+# libgtk-layer-shell (Wayland layer-shell) gets loaded on an X11 VNC display and
+# crashes xfdesktop -> black desktop. Fix verified 2026-09-08.
+export GDK_BACKEND=x11
 export XDG_SESSION_TYPE=x11
 export XDG_CURRENT_DESKTOP=XFCE

Why Not Remove libgtk-layer-shell0?

Attempting apt-get remove libgtk-layer-shell0 triggers a cascade of 9 reverse dependencies, removing xfce4-panel, xfce4-session, xfce4-settings, xfce4-terminal, xfce4-notifyd, and the entire XFCE desktop stack. The GDK_BACKEND=x11 fix is surgical — no packages removed, no side effects, zero risk.

Verification

1. xfdesktop running on display :2 after applying fix (PID 1825380 confirmed)
2. All XFCE packages remain installed (verified via dpkg)
3. gui.meiyoucheveux.com shows desktop content instead of black screen

Persistence

The fix is permanent because it’s in xstartup, which TigerVNC executes on every VNC session start. The current live session was manually fixed with GDK_BACKEND=x11 xfdesktop; the file edit ensures the next session restart picks it up automatically.

Related Infrastructure

Component	Detail
VNC display	:2 (TigerVNC, port 5902)
Web proxy	websockify port 6080 → VNC port 5902
Remote access	gui.meiyoucheveux.com (Cloudflare DNS Only, no orange cloud proxy)
Desktop	XFCE (xfce4-session, xfce4-panel, xfdesktop4)
Startup	~/.config/tigervnc/xstartup sourced by vncserver :2