tai/runbooks/x2go.md

service, symptoms, tags

service	symptoms	tags
x2go	x2go session fails to start, x2go black screen, x2go disconnects immediately, no desktop in session, authentication failure, x2go agent not starting, sound forwarding broken	x2go, nx, remote-desktop, x2goserver, x2goclient, session, desktop, xauth

Symptoms

• X2Go login succeeds but the session immediately disconnects
• Black screen after login
• Session is created but no desktop appears
• x2goruncommand error or X2Go Agent got stuck in state
• Sound, clipboard, or drive sharing fails while login itself works
• Authentication works over SSH but X2Go session startup fails

Diagnostics

Check X2Go services and packages

systemctl status x2goserver
systemctl status sshd
rpm -qa | grep x2go
apt list --installed | grep x2go
which x2golistsessions

X2Go depends on working SSH plus installed x2goserver and x2goserver-xsession components.

Check X2Go logs

journalctl -u x2goserver -n 100
journalctl -u sshd -n 100
ls -la ~/.x2go/
find ~/.x2go -type f -maxdepth 2 -print
x2golistsessions

Look for session startup failures, agent crashes, and auth helper errors.

Check desktop environment startup command

cat /etc/x2go/Xsession
cat ~/.xsession
cat ~/.Xclients

A missing or broken desktop session command is a common cause of black screens.

Check X11 and xauth availability

which xauth
xauth -V
ls -la ~/.Xauthority
which sshfs

X2Go requires a working X11 session setup. Missing xauth or a bad .Xauthority often breaks startup.

Filesystem and folder-sharing features may also depend on sshfs being installed.

Check session limits and stale sessions

x2golistsessions
x2gocleansessions
ulimit -a
loginctl list-sessions

Stale sessions or per-user process limits can prevent a new desktop from starting.

Check desktop dependencies

which startxfce4
which mate-session
which startplasma-x11
env | grep -E 'DESKTOP|XDG'

If the selected desktop command does not exist, X2Go may connect and then terminate immediately.

Remediation

Missing or broken desktop startup command: Set the session to a known-good desktop such as XFCE and verify the binary exists.

Corrupt Xauthority or stale X2Go session files: Remove stale session state and regenerate auth files:

rm -f ~/.Xauthority
rm -rf ~/.x2go/C-*

Missing xauth or X11 helpers: Install the missing X11 packages, then retry the session.

Required server packages missing: Install x2goserver and x2goserver-xsession first, then retry before debugging desktop startup.

SSH works but X2Go session fails: Treat it as a desktop startup or X11 auth problem, not an SSH transport problem.