Troubleshooting Connection Issues Unattended Sessions on Linux

This guide covers connection issues specific to Unattended Remote Support (URS) sessions on Linux remote devices.

Notes:

• X11 screen capture uses XCB.
• Wayland screen capture uses XDG Desktop Portal with PipeWire.
• Registration and command delivery depend on the ZohoAssistUrs system service.

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.

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.
• The Wayland compositor or portal backend lacks the required ScreenCast or RemoteDesktop capability.

Recommended steps:

• Check the active session: loginctl show-session <id> -p Type -p Active -p Display
• On X11, verify DISPLAY, XAUTHORITY, and xset; refer Section under "Display Missing or XAUTHORITY unreadable".
• On Wayland, verify xdg-desktop-portal, the desktop specific portal backend, PipeWire, and WirePlumber in the active user's session.
• Approve the portal request. If approval is unavailable or the compositor lacks the required capability, use Xorg.

Display capture returns error 25 (Black Screen) on X11

Issue:
activeDisplay exits with code 25, and the technician sees a black screen.

Exit codes:

• 10: Capture succeeded.
• 20: Capture failed.
• 25: A black screen was detected.
• 500: activeDisplay timed out.

Possible causes:

• A GPU driver problem, such as an NVIDIA driver failure after a kernel upgrade.
• DISPLAY points to an inactive Xorg session.
• No monitor is attached, leaving no usable root window size.

Recommended steps:

• Run: echo $DISPLAY / xrandr --listmonitors / xset q
• If DISPLAY is empty, follow steps under the Section "Display Missing or XAUTHORITY unreadable"
• If xrandr lists no monitors, follow steps under the Section "Headless Host".
• 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:
activeDisplay does not finish within one second.

Possible causes:

• The helper is blocked.
• The X server is unresponsive.
• The host is under heavy CPU or memory pressure.

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.
• Disable unused virtual outputs: xrandr --output <name> --off

DISPLAY is missing or XAUTHORITY is unreadable

Issue:
The log reports "cannot open display", and the agent cannot attach to the user's X11 session.

Possible causes:

• logind did not identify the correct graphical session.
• XAUTHORITY is missing or unreadable.
• Fast user switching or a nonstandard display manager path selected the wrong environment.

Recommended steps:

• Identify the active graphical user: 
  loginctl list-sessions 
loginctl show-session <id> -p Name -p Type -p Active -p Display
• Verify that the user's XAUTHORITY file exists and is readable.
• Restart the service: sudo systemctl restart ZohoAssistUrs.service

Important: Do not hard code DISPLAY=:0 unless the active session uses it. The code normally discovers the user's environment at runtime.

Monitor or Display Hardware

Headless host — no monitor connected

Issue:
The technician sees a 640×480 grey screen or no screen.

Possible causes:

• Without a physical monitor, the GPU exposes a minimal mode or no mode.

Recommended steps:

• Connect a physical monitor, fit a dummy plug, or configure a virtual display in xorg.conf: 
  Section "Screen" 
  Identifier "Default Screen" 
  SubSection "Display" 
    Virtual 1920 1080 
  EndSubSection 
EndSection
• Restart the display manager.

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.
• The root process could not start the audio helper as the active user with XDG_RUNTIME_DIR set.

Recommended steps:

• As the active user, 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.

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, 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.

Session Confirmation Dialog

Session auto rejected — "User did not respond"

Issue:
A session requiring confirmation times out.

Possible causes:

• The user did not select Allow or Deny within the configured window.

Recommended steps:

• Ask the user to respond promptly.
• Increase the timeout at Assist Console → Settings → Unattended → Confirmation Prompt → Timeout.
• For fully unattended hosts, select Settings → Unattended → Always Allow.

Note: The bundled dialog defaults to 120 seconds unless another timeout is supplied.

Confirmation dialog never appears

Issue:
The session is accepted or rejected without displaying a prompt.

Possible causes:

• The dialog cannot access the active display.
• D-Bus or Polkit prevented the window from starting.
• The host has no graphical session.

Recommended steps:

• Check for an active graphical session: 
  loginctl list-sessions 
loginctl show-session <id> -p Type -p Active -p Remote
• Check the user service; refer Section under URS Service Lifecycle.
• Check D-Bus: systemctl --user status dbus
• On a CLI only host, disable the prompt or attach a display.

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; check 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:
ZohoAssistUrs runs, but the device never appears online.

Possible causes:

• A firewall, proxy, DNS failure, or captive portal blocks application, DMS, or gateway 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:

• DMS registration and signaling require WebSocket connectivity.
• Screen and clipboard may use WebRTC P2P. Audio and secondary file transfer remain WebSocket based.

Proxy authentication fails

Issue:
The device registers initially but goes offline after restarting.

Possible causes:

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

Recommended steps:

• Configure the systemd unit: 
  [Service] 
Environment=https_proxy=http://user:pass@proxy:port 
Environment=http_proxy=http://user:pass@proxy:port 
Environment=no_proxy=localhost,127.0.0.1
• Reload and restart: 
  sudo systemctl daemon-reload 
sudo systemctl restart ZohoAssistUrs.service

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

WebSocket connection timeout

Issue:
The device remains at "connecting...", and the log reports failure 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 service repeatedly restarts after agent crashes.

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.

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.

URS Service Lifecycle

"Service unavailable" when starting a session

Issue:
Attended sessions work, but unattended sessions fail immediately.

Possible causes:

• ZohoAssistUrs.service is stopped, or ZohoAssistUrsUser.service is unavailable.

Recommended steps:

• Check the system service and journal: 
  sudo systemctl status ZohoAssistUrs.service 
sudo journalctl -u ZohoAssistUrs.service -n 200 --no-pager
• Re-enable and start it: 
  sudo systemctl unmask ZohoAssistUrs.service 
sudo systemctl enable --now ZohoAssistUrs.service
• As the logged in user, check: systemctl --user status ZohoAssistUrsUser.service

Session drops during a package upgrade

Issue:
A live session disconnects and reconnects later.

Possible causes:

• The Upgrader stopped URS while installing a version.

Recommended steps:

• Retry after installation finishes.
• Verify: sudo systemctl status ZohoAssistUrs.service

Crash dump appears in the log directory or /tmp

Issue:
One or more of these files exist in /var/log/ZohoAssist or /tmp: urs_crash.dmp / rds_crash.dmp / rds_user_crash.dmp / upgrader_crash.dmp / zsysmanager_crash.dmp

Possible causes:

• The starter, URS, user helper, upgrader, or system manager process panicked.

Recommended steps:

• Collect the crash files: 
  sudo find /tmp /var/log/ZohoAssist -maxdepth 1 -type f -name '*_crash.dmp' -print 
sudo tar czf /tmp/zohoassist-crash.tgz /var/log/ZohoAssist $(find /tmp -maxdepth 1 -type f -name '*_crash.dmp')
• Send /tmp/zohoassist-crash.tgz to Zoho Assist Support.

Active User and Session Detection

"No active display" on a logged in machine

Issue:
A user is logged in graphically, but the agent reports no active user.

Possible causes:

• No active logind session has a usable display/runtime environment.
• Fast user switching selected the wrong session.

Recommended steps:

• Inspect sessions: 
  loginctl list-sessions 
loginctl show-session <id> -p Type -p Active -p Remote -p Display
• On Wayland, verify portal, PipeWire, WirePlumber, and D-Bus. If the portal request cannot be satisfied, use Xorg.
• Log out inactive users if multiple users are logged in.

Only the lock screen or login greeter is visible

Issue:
A confirmation prompt does not appear on a locked screen or GDM, SDDM, or LightDM greeter.

Possible causes:

• URS detects the lock or greeter, skips the dialog, and reports SCREEN_LOCKED.

Recommended steps:

• Ask the user to log in or unlock the screen, then retry.
• For a genuinely unattended host, configure confirmation policy so no local prompt is required.

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.