Skip to main content

Troubleshooting

"org.gnome.Mutter.RemoteDesktop was not provided by any .service files"​

There is no GNOME session for Waylo to capture. Mutter publishes its ScreenCast/RemoteDesktop APIs only from inside a live session, so a machine sitting at a console — or at the greeter with nobody logged in — has no capture API at all. Check all four of these line up:

pgrep -x gnome-shell                    # a shell owned by the user Waylo runs as
systemctl status display-manager        # enabled, and not masked
grep -E 'Wayland|AutomaticLogin' /etc/gdm3/custom.conf
loginctl show-session "$(loginctl show-user "$(id -u)" --value -p Display)" \
  --value -p Type                       # must be: wayland

A box that was provisioned headless — or set up for xrdp — usually has the display manager masked and GDM left on Xorg, which is exactly the combination that produces this error:

sudo systemctl unmask gdm.service gdm3.service
sudo systemctl daemon-reload
# then, in the [daemon] section of /etc/gdm3/custom.conf
# (/etc/gdm/custom.conf on non-Debian):
#   AutomaticLoginEnable=true
#   AutomaticLogin=<the user Waylo runs as>
#   WaylandEnable=true
sudo systemctl start display-manager

Re-running the installer offers to do all of that for you.

Nothing plugged into the machine is fine: with no physical monitors Waylo records a 1920×1080 virtual display instead, so a monitor-less box streams a full desktop.

"Session creation inhibited"​

GNOME's Mutter refuses to start a capture session while the screen is locked unless the allow-locked-remote-desktop extension is loaded. Waylo now recovers automatically — it unlocks the screen and retries, so the connection still succeeds. To keep the screen locked while streaming, install and load the extension:

bash ~/.local/share/waylo/scripts/install-extension.sh
# log out and back in (Xorg: Alt+F2 → r → Enter) so GNOME loads it
gnome-extensions info allowlockedremotedesktop@kamens.us   # want: State: ACTIVE

If it stays INITIALIZED no matter how often you enable it, check the shell-wide kill switch — some provisioning images and remote-support agents set it, and it switches off every user extension:

gsettings get org.gnome.shell disable-user-extensions   # want: false
gsettings set org.gnome.shell disable-user-extensions false

See Unattended Access.

Login always fails​

  • SSH server must be installed and running — Waylo verifies logins over SSH to localhost: systemctl status ssh (Debian/Ubuntu) or systemctl status sshd (Fedora). Install with e.g. sudo apt install openssh-server.
  • Session owner only — you must log in as the user who owns the desktop session (the account Waylo runs as); another user's credentials are rejected.
  • Sudo — the account needs sudo access.

"Too many failed login attempts"​

After 5 failed attempts within 15 minutes an address is locked out. Wait a few minutes and try again with the correct credentials.

Input not working​

  • Click the video to capture the pointer; keyboard and scroll are only forwarded while captured.
  • Press Esc or Ctrl+M to release capture.
  • Check the browser console for errors.

Picture is smooth but bandwidth is high​

You're probably on MJPEG because the host has no H.264 encoder. Install the GStreamer bad/ugly plugin sets to get vah264enc (hardware), x264enc, or openh264enc. See Performance and Video Pipeline.

Poor performance​

  • Lower the frame rate and quality (login screen or toolbar ⚙️).
  • Reduce resolution: waylo --width=1280 --height=720.
  • Enable reduced effects to cut animation-driven screen change.

No audio​

Audio needs a browser with the WebCodecs AudioDecoder and PulseAudio/PipeWire on the host (pulsesrc). Where either is missing, video and input still work; audio is simply unavailable. Check the toolbar isn't muted.

xrdp coexistence / a stale locked session​

If Waylo captures an xrdp session, Waylo and xrdp share the same GNOME session (a single monitor named rdp0). A stale lock on that session can block new xrdp logins and inhibit Waylo capture. Waylo's auto-unlock clears the inhibit for its own connection; if xrdp logins still fail, unlock or end the stale session on the host.

Also check the local display manager is still enabled — a box set up for xrdp often has gdm.service masked, which leaves no local GNOME session for Waylo to capture at all, and Waylo then fails with the missing-RemoteDesktop error above.

The service won't start​

systemctl --user status waylo
journalctl --user -u waylo -n 50

Common causes: the port is already in use (change --port), or the unit ran before the graphical session was ready (it's bound to graphical-session.target and should retry). For access after logout, ensure linger is enabled: loginctl enable-linger "$USER".