Skip to content
LabTether

Desktop Session Issues

Desktop sessions fail to start, drop unexpectedly, show a black screen, or related features like session recording and Wake-on-LAN are not working.

Session won't start

The most common desktop problem. You click connect and nothing happens, the viewer times out, or you get an error immediately.

Is the node online? Desktop sessions require an active agent connection. If the node is offline, fix that first -- see Node Won't Connect.

Protocol prerequisites. Different protocols have different requirements on the target:

  • VNC (Linux): Requires x11vnc, Xvfb, xterm, xdotool, and GStreamer runtime. Check quickly:

    command -v x11vnc && command -v Xvfb && command -v xterm && command -v xdotool && command -v gst-launch-1.0

    If anything is missing, re-run the agent installer with --install-vnc-prereqs.

  • VNC (macOS): Screen Sharing must be enabled. Go to System Settings > General > Sharing > Screen Sharing and confirm it is on. If needed:

    sudo "/System/Library/CoreServices/RemoteManagement/ARDAgent.app/Contents/Resources/kickstart" \
  -configure -access -on -users "$USER" -privs -all -restart -agent

  • RDP: Requires a running guacd sidecar and valid credentials for the target Windows session.

  • SPICE: Requires VM-level SPICE support and a valid ticket. SPICE tickets are single-use -- if a previous attempt consumed the ticket, generate a new one.

  • WebRTC: Requires GStreamer and a working signaling path. If WebRTC is unavailable, the console should fall back to VNC automatically. If it does not, check the agent logs for webrtc_unavailable_reason.

Stream ticket validation. Every desktop session starts with a stream ticket. If the ticket request fails:

# Test ticket issuance
curl -s -X POST https://<hub>/api/desktop/sessions/<session-id>/stream-ticket \
  -H "Authorization: Bearer <token>"

A 201 response with a stream_path means the ticket path is working. A 4xx error points to an auth or session state problem.

Desktop diagnostic endpoint. For Linux nodes with agent-backed desktop, the hub exposes a diagnostic endpoint:

curl -s -X POST https://<hub>/api/desktop/diagnose/<asset-id> \
  -H "Authorization: Bearer <token>"

This returns Xvfb state, x11vnc status, GStreamer capabilities, WebRTC availability, and framebuffer content checks -- everything you need to pinpoint what is missing on the target.

Tip: If the Remote View panel is missing entirely for a node that should support desktop, confirm the node is agent-connected (not just discovered via a connector). Desktop sessions require an active agent on the target.

Session drops

The session starts successfully but disconnects after some time.

Network stability. Desktop sessions stream continuous data over a WebSocket connection. Even brief network interruptions will drop the session. If you are on a flaky connection, try lowering the quality setting to reduce bandwidth requirements.

Resource pressure on the target. A fully saturated CPU or exhausted memory on the target host can cause the VNC/WebRTC server process to stall or crash. Check resource usage on the target:

top -bn1 | head -15

Timeout settings. If sessions drop after a consistent interval (for example, exactly 30 minutes), the problem is likely a timeout -- either in LabTether's session configuration, a reverse proxy in front of the hub, or a firewall's idle connection timeout. Check each layer's timeout settings.

TLS and proxy issues. If the hub runs behind a reverse proxy with TLS termination, confirm that:

  • The proxy supports long-lived WebSocket connections.
  • The proxy's idle timeout is longer than the expected session duration.
  • TLS trust is consistent between the console origin and the stream endpoint.

Recording issues

Desktop session recordings are not being saved or cannot be played back.

Recording not saving:

  • Confirm the protocol/session path supports recording. Not all protocol combinations support it.
  • Check that the hub has sufficient disk space for recording storage.
  • Verify recording lifecycle events in the hub logs -- look for errors during the recording finalization step.
  • Check retention settings. If retention is set aggressively short, recordings may be cleaned up before you look for them.

Playback problems:

  • If a recording appears in the list but won't play, the recording file may be incomplete (for example, if the session crashed before the recording was finalized).
  • Try downloading the recording file directly and playing it with a local tool to determine whether the problem is in the file or in the console's playback UI.

Tip: For a quick sanity check, start a desktop session with recording enabled, perform a few actions, disconnect cleanly, and verify the recording appears with the expected duration.

Wake-on-LAN failures

You send a Wake-on-LAN command but the target machine does not power on.

Hardware prerequisites. WoL requires:

  • The target NIC supports WoL and it is enabled in BIOS/UEFI.
  • The target OS has not disabled WoL on shutdown (some Linux distributions disable it by default; check with ethtool <interface> | grep Wake-on).
  • The target is connected via Ethernet, not Wi-Fi (most Wi-Fi adapters do not support WoL).

Network path for magic packets. WoL magic packets are Layer 2 broadcasts. They do not route across subnets by default. For WoL to work:

  • The hub (or a relay agent) must be on the same Layer 2 network as the target.
  • If the target is on a different VLAN, you need a WoL relay or directed broadcast configured on the router.

MAC address accuracy. The magic packet targets a specific MAC address. If the node's MAC address changed (for example, after a NIC replacement) or was recorded incorrectly, the packet will be ignored. Verify the MAC address in the node's details matches the actual hardware.

Confirming WoL support on the target:

# Check current WoL setting (Linux, while the machine is still on)
sudo ethtool <interface> | grep Wake-on

# "g" means WoL is enabled; "d" means disabled
# Enable it if needed:
sudo ethtool -s <interface> wol g

Warning: WoL settings configured with ethtool do not always persist across reboots. For permanent configuration, add the setting to a network manager configuration file or a systemd unit.