tai/runbooks/xorg.md

service, symptoms, tags

service	symptoms	tags
xorg	xorg black screen, display manager loop, no screens found, failed to start X server, GPU driver error, xrandr missing outputs, login screen not appearing	xorg, x11, display, gpu, drm, xrandr, gdm, sddm, lightdm

Symptoms

• Black screen after graphical boot
• Display manager loops back to login
• no screens found in Xorg log
• External monitors are missing or not detected
• X server fails after a driver update
• startx exits immediately with display or device errors

Diagnostics

Check display manager and Xorg service path

systemctl status display-manager
systemctl status gdm
systemctl status sddm
systemctl status lightdm

If the display manager is failing, inspect its logs before focusing on Xorg itself.

Check Xorg logs

find /var/log -name 'Xorg*.log' -o -name 'Xorg.*.log'
grep -E '\(EE\)|\(WW\)' /var/log/Xorg.0.log
journalctl -b | grep -iE 'xorg|gdm|sddm|lightdm'
ls -la ~/.local/share/xorg/

Look for: no screens found, GPU module load failures, and permission/device access errors.

On rootless Xorg, logs are often under ~/.local/share/xorg/Xorg.0.log instead of /var/log/.

Check DRM and GPU driver state

lspci -k | grep -A3 -E 'VGA|3D|Display'
lsmod | grep -E 'nouveau|nvidia|amdgpu|i915'
dmesg | grep -iE 'drm|gpu|nvidia|amdgpu|i915'

Driver mismatches after kernel updates are a common cause of X startup failures.

Check monitor detection and permissions

loginctl session-status
xrandr --query
ls -la /dev/dri/
ps -o user= -C Xorg

If /dev/dri/* permissions or seat assignment are wrong, X may fail to access the GPU.

Check X configuration files

find /etc/X11 -maxdepth 3 -type f
cat /etc/X11/xorg.conf
cat /etc/X11/xorg.conf.d/*.conf
ls -la ~/.xinitrc ~/.xserverrc

Custom Device, Monitor, or Screen sections often break auto-detection.

An empty or broken .xinitrc can produce a black screen even when the X server itself started correctly.

Remediation

Bad static Xorg config: Move custom config aside and let auto-detection work unless the hardware truly needs manual config.

Driver mismatch after update: Reinstall the GPU driver package matching the running kernel and reboot or restart the display manager.

no screens found: Check whether the correct DRM module loaded and whether the display manager is running on the expected seat.

Display manager loop: Correlate Xorg errors with PAM/auth logs; some loops are session startup failures, not graphics failures.

Framebuffer mode failure: If X falls back to fbdev and errors with framebuffer/bus ID messages, remove the generic fbdev driver package and let Xorg use the proper modesetting or vendor driver.

SocketCreateListener() failed: Check for stale sockets in /tmp/.X11-unix, especially after previous root-run Xorg sessions.