Troubleshooting Remote Support Connection Issues on Linux Remote Devices

This article helps you resolve errors you may encounter when setting up or running a remote support session on a Linux device. Each section covers the issue, possible causes, and recommended steps to resolve it.

Notes:

• X11 screen capture uses XCB.
• Wayland screen capture uses XDG Desktop Portal with PipeWire.

Display Server (Wayland / X11)

Grey or black screen on the technician side

Issue:
The session connects, but the technician sees only a grey or black rectangle. Mouse and keyboard appear to work, but the screen remains blank.

Possible causes:

• On X11, the agent cannot access the active display or XAUTHORITY file, or XCB capture failed.
• On Wayland, the portal ScreenCast request failed, was denied, or PipeWire could not open the stream.

Recommended steps:

• Check the session type: echo $XDG_SESSION_TYPE
• On X11, verify DISPLAY, XAUTHORITY, and xset; refer the steps mentioned under "DISPLAY is missing or XAUTHORITY is unreadable"
• On Wayland, verify xdg-desktop-portal, the desktop specific portal backend, PipeWire, and WirePlumber for the logged in user.
• Restart the session and approve the portal screen sharing request.
• If the required portal capabilities are unavailable, use GNOME on Xorg or Plasma (X11).

Display capture returns error 25 (Black Screen) on X11

Issue:
The activeDisplay helper exits with code 25; the technician sees a black screen even on X11 systems.

Note: Exit code 10 means capture succeeded. Exit code 20 means the capture call itself failed. Exit code 25 specifically means a black screen was detected. Exit code 500 is a timeout.

Possible causes:

• A GPU driver problem, such as an NVIDIA proprietary driver failure after a kernel upgrade.
• DISPLAY points to an inactive Xorg session.
• No monitor is attached, leaving no usable root window size.
• GPU driver issue — for example, an NVIDIA proprietary driver after a kernel upgrade.
• The DISPLAY environment variable is incorrect or pointing to a dead Xorg session.
• The X server is running, but no monitor is attached, so the root window has zero usable size.

Recommended steps:

• Run: 
  echo $DISPLAY 
xrandr --listmonitors 
xset q
• If DISPLAY is empty, follow the steps mentioned under "DISPLAY is missing or XAUTHORITY is unreadable"
• If xrandr lists no monitors, attach a physical or virtual display.
• If xset fails, repair or roll back the GPU driver.

Notes:

• The agent checks through XCB, then falls back to activeDisplay and, if the dynamic binary cannot execute, activeDisplayS.
• Code 25 triggers one cursor movement retry before the display is rejected.

Active display detection returns error 500 (Timeout)

Issue:
Screen sharing stutters with frames stopping every few seconds, caused by activeDisplay failing to respond within one second.

Possible causes:

• The activeDisplay helper is blocked or slow to respond typically due to saturated CPU, memory pressure/swapping, an unresponsive X server, or a slow xrandr query on a host with many virtual outputs.

Recommended steps:

• Check system load: 
  top -b -n 1 | head -20 
free -h
• Stop runaway processes.
• Add swap space or RAM if memory is exhausted.
• If many virtual outputs are present, disable unused ones with xrandr --output <name> --off

DISPLAY is missing or XAUTHORITY is unreadable

Issue:
The log reports "cannot open display", and the technician cannot start a session.

Possible causes:

• A manually started agent did not inherit the user's DISPLAY or XAUTHORITY environment.

Recommended steps:

• Set the variables before starting the agent: 
  export DISPLAY=:0 
export XAUTHORITY=$(ls /home/*/.Xauthority | head -1)
• Confirm that the selected display and XAUTHORITY file belong to the active graphical user.

Monitor or Display Hardware

Low end or ARM device is slow or laggy

Issue:
Input is delayed, and screen updates skip frames.

Possible causes:

• VPX software encoding cannot process the selected resolution and frame rate fast enough.
• A headless device has no usable display mode.

Recommended steps:

• Lower session quality and display resolution.
• Disable unused monitors.
• Provide a usable physical or virtual display.

Multi monitor switching does not work on X11

Issue:
Selecting another monitor does not change the displayed screen.

Possible causes:

• Required XCB runtime libraries are missing.

Recommended steps:

• Check monitor detection: xrandr --listmonitors
• On Debian or Ubuntu, install the libraries: sudo apt-get install libxcb-randr0 libxcb-shm0 libxcb-xfixes0
• Restart the agent session.

Note: Wayland obtains monitor streams through XDG Desktop Portal and does not use these XCB libraries.

Audio

No audio during a remote session

Issue:
Video works, but the technician hears nothing.

Possible causes:

• No PulseAudio compatible server is running. The agent uses libpulse; PipeWire systems provide compatibility through pipewire-pulse.
• No default sink is configured.

Recommended steps:

• Check the audio server and sink: 
  systemctl --user status pulseaudio.service 
systemctl --user status pipewire-pulse.service 
pactl info | grep 'Default Sink'
• Start the service used by the desktop. 
  PulseAudio: systemctl --user enable --now pulseaudio.service 
  PipeWire: systemctl --user enable --now pipewire.service pipewire-pulse.service wireplumber.service
• If no sink exists, create a virtual sink: 
  pactl load-module module-null-sink sink_name=virt 
pactl set-default-sink virt

Note: Audio is Opus encoded and sent over a secondary WebSocket.

Audio drops out

Issue:
Audio starts and then stops.

Possible causes:

• The default sink changed, and its new .monitor source could not be opened.
• The PulseAudio compatible server stopped responding or pa_simple_read failed.
• The secondary audio WebSocket disconnected.

Recommended steps:

• Restart the active compatibility service: systemctl --user restart pulseaudio.service or systemctl --user restart pipewire-pulse.service
• Avoid changing the default sink during a session.
• Check section under Network, Firewall and Proxy  for WebSocket or gateway problems.

Note: Audio uses a secondary secure WebSocket on TCP port 443.

Keyboard and Mouse Input

Mouse and keyboard have no effect

Issue:
Technician input does not affect the remote desktop.

Possible causes:

• Local user input conflicts with injected events.
• High CPU usage stalls input processing.
• On X11, required XCB/X11 input libraries are missing.
• On Wayland, portal RemoteDesktop/EIS failed or remote control permission was denied.

Recommended steps:

• Check CPU usage and restart the agent if necessary.
• On Debian or Ubuntu X11 systems, install the input libraries: sudo apt-get install libxcb-xtest0 libxcb-xinput0
• On Wayland, restart the session and approve remote control access.

Wrong characters are typed

Issue:
A typed key produces a different character remotely.

Possible causes:

• The remote XKB layout differs from the technician layout.

Recommended steps:

• Check the layout: setxkbmap -query
• Set the required layout: setxkbmap us
• Make the change permanent in the desktop Keyboard Settings panel.

Clipboard

Clipboard synchronization does not work

Issue:
Copying on one side does not paste on the other.

Possible causes:

• Session policy disables clipboard sharing.
• On X11, the agent cannot open the display or own the CLIPBOARD selection.
• On Wayland, the portal clipboard request or listener failed.

Recommended steps:

• Confirm clipboard permission at Assist Console → Settings → Permissions.
• On X11, verify DISPLAY and XAUTHORITY.
• On Wayland, restart the session and approve the portal request.

Note: Clipboard access is implemented directly; xclip and wl-clipboard are not required.

Clipboard contents are truncated

Issue:
Text over approximately 50 KB loses trailing content.

Possible causes:

• The Linux UI limits text clipboard content to 50,000 bytes.

Recommended steps:

• Use File Transfer for larger payloads.

Licensing and Permissions

Feature is greyed out or shows "feature disabled"

Issue:
Screen sharing, file transfer, chat, or annotation is unavailable.

Possible causes:

• The handshake omitted the feature from remote_support_license or permissions. Features are enabled only when present in the response.

Recommended steps:

• Verify the account license and technician permissions.
• Start a new session to receive a new handshake response.

File Transfer

File transfer fails to start

Issue:
"Transfer failed" appears immediately.

Possible causes:

• The primary session connection failed.
• The optional secondary file transfer WebSocket could not reach its server supplied gateway.
• The agent cannot read the source or write the destination.
• Server policy disables file transfer.

Recommended steps:

• Allow outbound WebSocket traffic on TCP port 443; refer to section under Network, Firewall and Proxy
• Check path permissions for the agent user.
• Check Assist Console → Settings → Permissions.

Note: Transfer starts on the session connection and may move to a secondary WebSocket. No local listening port is used.

Network, Firewall and Proxy

Cannot reach the gateway — port 443 blocked

Issue:
The agent fails to connect.

Possible causes:

• A firewall, proxy, DNS failure, or captive portal blocks HTTPS or WebSocket traffic on TCP port 443.

Recommended steps:

• Allow these domains on TCP port 443: *.zoho.com / *.zohoassist.com
• Test connectivity: curl -v https://assist.zoho.com/

Notes:

• The gateway WebSocket is required for signaling and fallback transport.
• Screen and clipboard may use WebRTC P2P. Audio and secondary file transfer remain WebSocket based.

Proxy authentication fails

Issue:
Initial installation connects, but later sessions time out.

Possible causes:

• Proxy credentials changed or are incorrect.
• The proxy requires unsupported NTLM or Kerberos authentication.

Recommended steps:

• Configure the proxy through Assist tray icon → Settings → Proxy, or set: 
  export https_proxy=http://user:pass@proxy:port 
export http_proxy=http://user:pass@proxy:port 
export no_proxy=localhost,127.0.0.1

Note: NTLM or Kerberos proxies require an authenticating relay such as cntlm.

Peer connection (WebRTC / P2P) fails

Issue:
The session works, but P2P never activates and performance is lower.

Possible causes:

• UDP is blocked, or the session config STUN servers are unreachable.
• Symmetric NAT on both sides prevents a direct connection.

Recommended steps:

• Allow outbound UDP to the exact STUN URLs supplied in the session configuration.
• Do not assume a fixed STUN port range; none is hard coded by this implementation.

Notes:

• Pion WebRTC automatically falls back to the existing WebSocket connection when P2P fails.
• No TURN credentials are configured in the current implementation.

WebSocket connection timeout

Issue:
The session remains at "connecting..." and fails after about 20 seconds.

Possible causes:

• The 20 second WebSocket handshake timeout was exceeded due to loss, an MTU mismatch, or gateway load.

Recommended steps:

• Test packet loss and MTU: ping -M do -s 1472 assist.zoho.com
• If fragmentation is required, repair PMTUD or lower the interface MTU to 1400.

Performance and Memory

"Memory allocation failed" — agent crashes repeatedly

Issue:
The agent repeatedly crashes and restarts.

Possible causes:

• The OOM killer terminated the process.
• A cgroup memory limit or ulimit was reached.

Recommended steps:

• Check memory: free -h / dmesg | grep -i 'killed process'
• Add swap space or RAM.
• Reduce session resolution.

"CRASHED RS agent startup error"

Issue:
Screen sharing is immediately unavailable.

Possible causes:

• On X11, required XCB libraries are missing or the display is inaccessible.
• On Wayland, the portal or PipeWire stream failed.
• A GPU driver update broke capture.

Recommended steps:

• On Debian or Ubuntu X11 systems, install the libraries: sudo apt-get install libxcb1 libxcb-shm0 libxcb-randr0 libxcb-xfixes0
• On Wayland, check the services described in Section under Display server
• Repair or roll back the GPU driver if the issue followed an update.

Session is slow — high CPU usage

Issue:
Screen updates lag, and one CPU core remains at 100%.

Possible causes:

• VPX software encoding runs on a low end CPU.
• A high resolution or multi monitor framebuffer is captured.
• Low memory causes swapping.

Recommended steps:

• Lower session quality.
• Disable unused monitors: xrandr --output <name> --off
• Reduce capture load or upgrade the hardware.

Note: The implementation selects VPX software encoding, not hardware accelerated encoding.

Locale and Keyboard Layout

Non ASCII characters appear as boxes or question marks

Issue:
Accented or CJK characters in file names or chat messages are corrupted.

Possible causes:

• The locale is C or POSIX.
• UTF-8 fonts are missing.

Recommended steps:

• Check the locale: locale
• On Debian or Ubuntu, install locales and fonts: 
  sudo apt-get install locales fonts-noto fonts-noto-cjk 
sudo locale-gen en_US.UTF-8 
sudo update-locale LANG=en_US.UTF-8
• Log out and back in.