2.9 KiB
service, symptoms, tags
| service | symptoms | tags |
|---|---|---|
| wayland | wayland session fails, gdm falls back to xorg, black screen on login, fractional scaling broken, screen sharing broken, remote desktop broken, wlroots crash, compositor crash | wayland, compositor, gnome, kde, mutter, wlroots, pipewire, xwayland, graphics |
Symptoms
- User selects a Wayland session but is returned to login
- GDM or another display manager falls back to Xorg
- Screen sharing, remote desktop, or clipboard integration is broken
- Apps requiring XWayland fail while native Wayland apps work
- Fractional scaling or multi-monitor layout behaves incorrectly
- Wayland compositor crashes after login
Diagnostics
Confirm the active session type
echo $XDG_SESSION_TYPE
loginctl show-session $XDG_SESSION_ID -p Type
echo $WAYLAND_DISPLAY
If the session type is x11, you are not debugging an active Wayland session.
Check display manager and compositor logs
systemctl status gdm
journalctl -b | grep -iE 'wayland|mutter|kwin|wlroots|xwayland'
journalctl -b | grep -i 'renderer for'
Look for compositor crashes, GPU driver incompatibilities, and forced Xorg fallback messages.
Check XWayland and PipeWire components
which Xwayland
systemctl --user status pipewire
systemctl --user status xdg-desktop-portal
systemctl --user status xdg-desktop-portal-gnome
systemctl --user status xdg-desktop-portal-kde
xlsclients -l
Broken screen sharing is often a PipeWire or portal issue, not a compositor issue.
xlsclients -l helps identify apps that are actually running under XWayland rather than native Wayland.
Check GPU compatibility
lspci -k | grep -A3 -E 'VGA|3D|Display'
lsmod | grep -E 'nvidia|nouveau|amdgpu|i915'
Wayland support quality depends heavily on the GPU driver stack.
Check environment and session overrides
env | grep -E 'WAYLAND|XDG|GDK_BACKEND|QT_QPA_PLATFORM'
cat /etc/gdm/custom.conf
wayland-info
Environment overrides can force apps onto X11 or disable Wayland entirely.
For NVIDIA systems, confirm the compositor is using a supported buffer path (GBM on current drivers is the expected default).
Remediation
Wayland disabled in display manager config:
Check WaylandEnable=false or similar settings and remove the override if unintended.
Fallback to Xorg on unsupported GPU stack: Upgrade or change the graphics driver; Wayland stability is often limited by the driver, not the compositor.
Screen sharing broken:
Fix PipeWire and xdg-desktop-portal services before changing compositor settings.
XWayland-only app failures:
Treat them separately from native Wayland issues; confirm Xwayland is installed and launching.
Remote desktop, VM, or game input grabbing is broken: This is often a Wayland protocol/compositor support limitation, not a generic keyboard bug. Check compositor support for pointer constraints, relative pointer, and keyboard shortcut inhibit protocols.