90 lines
2.9 KiB
Markdown
90 lines
2.9 KiB
Markdown
---
|
|
service: wayland
|
|
symptoms: 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
|
|
tags: 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.
|