Troubleshooting

Common problems, and what does not work yet.

Connecting

"Could not connect" or a timeout on a direct connection

• Check the address and that both computers are on the same network or VPN.
• On the computer being controlled, open Settings → Direct connections and make sure it is turned on. The main page shows the port under the address.
• The most common cause is a firewall on the computer being controlled. If the attempt waits about ten seconds and reports no answer while ping works, that is it. Omarchy blocks incoming connections by default. See Firewall: allow direct connections for the command on each system.
• The firewall matters in one direction only: on the computer being controlled. To check which side is blocked, try connecting the other way round.
• If the main page says the port is unavailable, another program is using it. Pick another port in Settings.

"Wrong password"

• The one-time password changes after each session. Ask for the current one.
• After five wrong attempts, wait a minute before trying again.

"Device is offline" when connecting by ID

• On that computer run humble status. The Server line should say online.
• If it shows an error about the server's key, the server's server.key has changed. Restore the original key, or enroll the device again.
• On Linux and macOS the computer is only reachable while a user is logged in to the desktop.

"Sign in to your Humble server to connect by ID"

Connecting by ID needs an account. Open the Computers page and sign in first.

The Connect button in the dashboard does nothing

The browser hands the link to the desktop app. Install the app on the computer you are browsing from, start it once, and allow the browser to open Humble links when it asks.

Screen and input

"No displays" on a Linux computer with no monitor (or an HDMI dummy plug)

With no monitor connected the desktop has no screen to share. An HDMI dummy plug is meant to fix that, but some computers do not detect one: cat /sys/class/drm/card*-*/status then shows every connector as disconnected. Make the computer believe a 1920×1080 monitor is always connected, with or without a plug, and restart:

sudo ./virtual-display.sh            # packaging/linux/virtual-display.sh in the repository
sudo ./virtual-display.sh --remove   # undo

It uses the first HDMI connector (HDMI-A-1); name another as the argument. Fedora, Debian and Ubuntu are supported. The computer must also sign someone in to the desktop by itself after a restart (automatic login in Settings → Users, or AutomaticLoginEnable in GDM's custom.conf): Humble shares that user's desktop, not the login screen.

Black screen, or "Waiting for the first frame"

• A message at the top of the session window says why the remote computer could not capture its screen. Read it first.
• KDE on Wayland: someone must accept the screen-sharing prompt on the remote computer. GNOME (from Humble 0.10.0), Hyprland (Omarchy) and sway need no prompt: on GNOME, Humble records through GNOME's own screen-cast service, as GNOME's Remote Desktop does, and GNOME shows its screen-sharing icon in the top bar meanwhile. Use Humble 0.10.0 or newer on the remote GNOME computer; an older one waits for someone to press Share there.
• "DISPLAY is not set": Humble on the remote computer was started outside the desktop session, for example over SSH. Start it from the desktop, or use the background service.
• macOS: grant Screen Recording to Humble and restart it.
• Windows: administrator prompts and the lock screen are shown and can be answered only when the remote computer runs Humble's background service (unattended access). Without it, the session says so and the picture returns when the desktop does.
• Try the slower capture method on the remote computer: set the environment variable HUMBLE_CAPTURE=poll and restart Humble.
• Use Actions → Refresh screen.

I can see the screen but cannot control it

• Check the right end of the toolbar. "view only" means your access level is View only, or View only is ticked under Actions.
• macOS: grant Accessibility to Humble and restart it.
• Wayland: a notice says input needs access to /dev/uinput. Install the package (it adds the required rule) and log out and in once. If you copied the binary by hand, install packaging/linux/60-humble-uinput.rules into /etc/udev/rules.d and run sudo modprobe uinput.
• Windows: programs running as administrator only accept input from the background service, not from the portable app. While one of them is the active window, all your input is ignored; the session window tells you which program it is.

The session window freezes after the first picture (Hyprland, other Wayland desktops)

In earlier builds a session window was only drawn together with the main Humble window, and Wayland desktops stop drawing windows that are hidden. When the main window was on another workspace, or behind the session in full screen, the session stopped updating, sent no input and ignored the close shortcut. Update Humble: session windows now draw on their own.

One limit remains: after you end a session while the main window is hidden, its window shows "Session ended" until the main window is visible again.

I am stuck in full screen

Press Right Ctrl + Right Alt + F, or move the pointer to the top-middle edge of the screen and choose End session. On a keyboard without a right Alt key, use the floating toolbar.

The Windows key or Alt+Tab acts on my own computer instead of the remote one

• Keys are sent to the remote computer only while the pointer is over the remote screen and the session window is the active window. Click inside the remote screen first.
• Controlling from Linux or macOS, these keys cannot be captured yet. Use the Send keys menu.

"Version mismatch" warning in the session window

The two computers run different Humble versions. The session still works and uses what both versions understand, so you can connect to an older computer and update it remotely. Features added since the older version may be missing until you update it. Hover over the warning in the toolbar to see both versions.

• From version 0.2.0 on, any newer Humble can control an older one, and the other way round.
• A computer still on the very first builds (before 0.2.0) can be controlled from a newer Humble. To control a newer computer from one of those old builds, update the old one first; it reports "incompatible protocol version".

The picture is old and does not change (Windows)

When the remote computer's monitors are asleep, Windows stops redrawing the desktop. Humble 0.2.0 and later ask Windows to keep the display awake for the length of a session. If you still see an old picture, the remote computer runs an older Humble: update it, or wake its display once by other means.

"Your mouse and keyboard are being ignored: an administrator window … is active"

Windows does not let an ordinary program send input to a window that runs with administrator rights, and it blocks all input while such a window is active. Install the background service on the remote computer with humble install (or the MSI). The service runs with system rights and can control every window.

Administrator prompts (UAC) and the lock screen

Windows shows administrator prompts, the lock screen and the sign-in screen on a separate, secure desktop. With Humble's background service on the remote computer (Humble 0.7.0 or later), the session follows it: you see the prompt and can answer it, then the desktop returns. Without the service, an ordinary program cannot see that desktop at all; the session tells you a prompt is open, and someone at the computer has to answer it. Ctrl+Alt+Del can always be sent with Send keys → Ctrl + Alt + Del.

The mouse lands in the wrong place with several monitors on Wayland

The virtual mouse covers the whole desktop and the desktop environment decides how that maps onto monitors. Use a single monitor on the remote computer, or an X11 session, if this affects you.

The picture is slow or blurry

Choose View → Optimize speed on a slow connection, or Optimize quality on a fast one. A static screen sends nothing, so a low frame-rate reading on an idle desktop is normal. On a slow network Humble softens the picture on purpose rather than falling behind (see Quality presets). Through a server, the server's own connection counts too: a relay with a slow upload limits every session through it.

The computer being controlled works hard, its fan spins up

Capturing and encoding a busy screen at 30 frames a second costs one to one and a half processor cores when the processor encodes, and roughly a third to a half less when the graphics card does. (Measured: a laptop with 11th-generation Intel graphics playing full-screen video went from 1.06 to 0.48 cores; a desktop with an NVIDIA card and a 2560×1440 screen showing fast-scrolling text went from 1.48 to 1.0.)

• Keep Settings → Advanced → Encode video on the graphics card on (the default). The log line video is encoded on the graphics card confirms it is used. On Linux this needs the VA-API driver: intel-media-driver for Intel graphics, Mesa for AMD.
• Leave Allow up to 60 frames per second off (the default): it doubles the work.
• View → Optimize speed lowers it further. A still screen costs little.

The session stutters while the computer is busy

Humble asks the system to put its own work first when a heavy job runs on either computer:

• Windows: Humble runs at above normal priority, and its video and sound threads use the Multimedia Class Scheduler, as media players do. Nothing to set up.
• Linux: an ordinary program cannot raise its own priority. The background service and the tray icon (humble-host.service, humble-tray.service) get ten times the usual share of the processor (CPUWeight=1000), so with them turned on Humble comes first among your programs; the Humble window opened from the tray shares it. Where RealtimeKit runs (rtkit, installed with PipeWire on most distributions), the video and sound threads also get a higher priority from it.

A job that keeps every core and the graphics card at full load can still slow Humble down. HUMBLE_PRIORITY=normal turns all of this off.

The picture breaks up or shows blocks after a graphics driver update

Turn off Settings → Advanced → Encode video on the graphics card on the computer being controlled and start a new session. If the graphics card fails during a session, Humble switches to the processor by itself.

No sound

• Check View → Play the remote sound in the session window and Settings → Sound.
• Both computers need a Humble version with sound. With an older one on either side, the session works without it.
• Sound from a Mac being controlled is not available yet. On Linux, the remote computer needs PulseAudio or PipeWire (with its PulseAudio service, the default on current distributions).
• If the remote computer cannot record its sound, the session window says why.

Files and clipboard

• Where did my upload go? Into the folder shown on the right of the file transfer window when you pressed ▶. A remote computer with Humble Viewer older than 0.13 puts it in Downloads/Humble of the account it runs under instead (with the Windows background service, C:\Windows\System32\config\systemprofile\Downloads\Humble).
• Copy and paste does nothing. Only text is synchronised, and only in sessions with Control access. On GNOME with Wayland the clipboard is only readable while the Humble window is focused.

Server

• Installer download says a file is missing. Put the app binaries in the server's dist folder. See Enable installer generation.
• Installers contain the wrong address. Set --public-url.
• "This installer link has expired". The installer expired, reached its limit or was revoked. Create a new one.
• Devices never come online behind a proxy. The proxy must pass WebSocket connections through to the server.
• Everyone appears to come from the same address in the audit log. Add --trust-proxy when running behind a reverse proxy.
• I created an admin from the terminal but cannot sign in. The command used a different data folder from the service. Run it as Administrator or with sudo, or pass the same --data.

Getting more detail

The app always keeps a log with debug detail, also when it was started from a menu or launcher. It is replaced once it grows past 5 MB (the previous one is kept as humble.log.old).

The log records each session (connecting, the remote version, video size, a line every 10 seconds with frames received, decoded and shown and input sent), notices from the remote computer, and crashes with a backtrace. A watchdog also logs when a window stops being drawn, and whether the app is busy or the desktop is simply not asking the window for frames. To follow it live:

tail -f ~/.local/state/humble/humble.log
humble --debug                              # the same detail on the console
RUST_LOG=debug humble --log-file humble.log # everything, including the graphics libraries, in a file of your choice
RUST_LOG=debug humble-server serve

In Windows PowerShell, set the variable first: $env:RUST_LOG = "debug". Service log locations are listed under Unattended access and Set up the server.

Not supported yet

• Controlling the Windows sign-in screen, lock screen and administrator prompts without the background service.
• Reaching a macOS computer before a user has logged in, or a Linux computer's desktop (its terminal and text console work through the headless service).
• Sound from a Mac being controlled, sending your microphone, session recording, and viewing a session in a web browser.
• A remote terminal or text console on Windows and macOS (Linux has the headless service).
• Capturing system keys (Super / Command, window switcher) when controlling from Linux or macOS.
• Direct connections through home routers without a server or a port-forward. Use a server or a VPN.
• Remembering the Wayland screen-sharing choice between restarts.
• Synchronising images or files through the clipboard.

How much each platform has been tested

If something does not behave as described on your system, please open an issue with the log output.