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/current/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. The login screen says so explicitly ("The password is right, but … can't use sudo"). If it says the sudo check timed out, run sudo true as that user: an extra prompt (a second factor, a PAM module waiting for input) makes the check hang.
  • "Incorrect password" with the right password — WayLo checks the password by signing in over SSH, so the SSH server must allow password logins. Both PasswordAuthentication yes and KbdInteractiveAuthentication yes work; with both set to no in /etc/ssh/sshd_config (common on hardened servers), every login is refused. sudo sshd -T | grep -Ei 'passwordauth|kbdinteractive' shows the effective values.

Stuck on "Connecting" or "Connection lost"​

Both screens count their attempts and how long the server has been unreachable, and both have a way out (Cancel / Disconnect) back to the login screen. While they retry, check that the WayLo service is running (systemctl --user status waylo) and that nothing between you and it (a reverse proxy, a VPN) drops WebSocket connections.

In the desktop client, a session that won't load names the likely cause — including an HTTPS/HTTP mismatch, which Edit on the connection fixes by toggling Connect over HTTPS.

"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​

  • Seamless mouse on (the default): the remote pointer follows yours whenever it is over the picture, and keys go to the remote once the pointer has been over it. Moving onto the toolbar hands the keyboard back to the browser.
  • Seamless mouse off: click the video to capture the pointer; keyboard and scroll are only forwarded while captured. Ctrl+M (or Esc, outside fullscreen) releases it. In fullscreen, Esc goes to the remote desktop — hold Esc to leave fullscreen.
  • 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 WAYLO_PORT in ~/.config/waylo/waylo.env), 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".

An update didn't take​

The update panel says the new version didn't pass its checks, or waylo-update status shows rolled-back: the previous version is running again, with its settings. The reason is at the end of the log that waylo-update status names (in ~/.local/state/waylo/log/); the new version's own output is in journalctl --user -u waylo. Once the problem is fixed, install again from the toolbar.

waylo-update status warning that an update was interrupted (the machine lost power mid-update, say) means the switch didn't finish: run waylo-update rollback to return to the previous release.