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.

Remote connection cannot be established (Wayland enabled)

Issue:

The remote support session cannot be established because the customer's Linux computer is running Wayland. Remote connections require an X11 session.

Possible causes:

• Wayland is enabled instead of X11 on the remote Linux computer (common on Fedora 25 and above).

Recommended steps:

Disabling Wayland requires administrator access and a system reboot. Steps vary by linux distribution and display manager.

Ubuntu

Ubuntu Desktop commonly uses GDM. To disable Wayland:

1. Open the GDM configuration file: sudo editor /etc/gdm3/custom.conf
2. Under the [daemon] section, uncomment the line #WaylandEnable=false (remove the # before the line)
3. Reboot the machine: sudo reboot
4. After signing in, confirm the session is using X11: echo "$XDG_SESSION_TYPE". The output should print x11.

Raspberry Pi OS (Raspbian)

1. Open the configuration tool:  sudo raspi-config
2. Navigate to Advanced Options > Wayland > X11, then reboot:  sudo reboot
3. After signing in, verify the change: echo "$XDG_SESSION_TYPE". The output should print x11.

Note: If the Wayland menu is unavailable, identify the active display manager before changing any configuration. Do not apply Ubuntu's GDM steps to Raspberry Pi OS.

Other Linux Distributions

Wayland is controlled by the installed display manager, and configuration paths vary across distributions. Before making changes, determine the active display manager:

Then consult that display manager's documentation  to disable Wayland or select X11. Common configuration files include:

GDM: Set WaylandEnable=false under the [daemon] section of custom.conf. The file location may be /etc/gdm3/custom.conf or /etc/gdm/custom.conf depending on the distribution. Older releases may use /etc/gdm3/daemon.conf or /etc/gdm/daemon.conf.

SDDM: Configuration files are commonly /etc/sddm.conf and /etc/sddm.conf.d/*.conf. Select an X11 session from the login screen or configure the distribution-supported session default. SDDM does not use GDM's WaylandEnable setting.

LightDM: Configuration files are commonly /etc/lightdm/lightdm.conf and /etc/lightdm/lightdm.conf.d/*.conf. Choose an X11 session from the login screen or set the session configuration appropriate to the desktop environment. LightDM does not use GDM's WaylandEnable setting.

To locate common display manager configuration files on the target host:

After changing the configuration, reboot and verify the session type: echo "$XDG_SESSION_TYPE"

The expected output is x11.

Note: Keep a console or SSH access path available while changing display manager settings so the configuration can be restored if the graphical login fails.

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.