---
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.