Troubleshooting Unattended Agent Installation Issues on Linux Devices

    This guide helps you troubleshoot common issues encountered while installing the Zoho Assist Unattended Agent on Linux devices. Installation failures may occur during agent installation, device registration, service startup, or dependency validation.

    Exit Codes and Installation Errors

    Exit Code 255

    Issue:

    • The installer (ZohoAssist.bin or ZohoAssist*.sh) exits with status code 255.
    • The installer window does not open or closes immediately.

    Possible causes:

    • The unattended device license limit has been reached.
    • The agent cannot connect to Zoho Assist servers due to DNS, firewall, proxy, or SSL issues.
    • The installer or activation token has expired.
    • The installer does not match your system architecture.

    Recommended steps:

    • Verify that your organization has available unattended device licenses.
    • Confirm the device can reach the Zoho Assist servers.
    • Generate and use a new installer from the Zoho Assist web console.
    • Ensure you are using the installer that matches your Linux distribution and system architecture.
    • Verify that the system date and time are correct.

    Exit Code 1 (No Internet Connection)

    Issue:
    The installer displays No Internet Connection, Connection Refused, or Network is Unreachable.

    Possible causes:

    • The installer cannot establish an internet connection.

    Recommended steps:

    • Verify internet connectivity.
    • Ensure DNS Recommended Steps is working correctly.
    • If the device uses a proxy server, configure the proxy before running the installer.
    • Retry the installation after connectivity is restored.

    Exit Codes 4 or 5 (Download Errors)

    Issue:

    • Installation stops during download.
    • Agent components are not extracted.
    • Application Error 200 or 300 is displayed.

    Possible causes:

    • SSL/TLS validation failure.
    • Interrupted download.
    • Incorrect system time.
    • Network proxy interfering with downloads.

    Recommended steps:

    • Update the system CA certificates.
    • Synchronize the system clock.
    • Disable TLS inspection if applicable or allowlist Zoho Assist domains.
    • Retry the installation.

    Application Error 200 (Session Expired)

    Issue:
    The installer displays Application Error 200 or Session Expired.

    Possible causes:

    • The installer session expired before all components were downloaded.

    Recommended steps:

    • Download a new installer from the Zoho Assist web console.
    • Avoid reusing expired installer packages.
    • Download the installer locally before running it if the network connection is slow.

    Permissions and Root Access

    Installation Requires Root Permission

    Issue:
    The installer displays:
    Installation Failed. Retry agent installation with root permission.

    Possible causes:

    • The installer was run without administrator (root) privileges.

    Recommended steps:

    • Run the installer using sudo or as the root user.

    Permission Errors After Installation

    Issue:

    • Permission denied errors appear during installation.
    • The unattended service fails to start.

    Possible causes:

    • Target directories are mounted with the noexec option.
    • SELinux or AppArmor prevents file execution.
    • Installation files were copied manually instead of installed correctly.

    Recommended steps:

    • Verify mount options.
    • Reinstall the package using the supported package manager.
    • Temporarily verify whether SELinux or AppArmor is blocking the installation.

    Temporary Directory Problems

    Issue:

    • The service fails to start.
    • Log files report errors while creating temporary files.

    Possible causes:

    • The /tmp directory is mounted with noexec.
    • Previous temporary files are preventing startup.
    • The /tmp partition is too small.

    Recommended steps:

    • Remove old temporary directories.
    • Recreate the required temporary directory.
    • Ensure sufficient free space is available.
    • Increase the size of the /tmp partition if necessary.

    Access Control

    SELinux Blocking the Agent

    Issue:
    The service starts but screen sharing, input control, or socket communication fails.

    Possible causes:

    • SELinux policies are preventing the agent from accessing required system resources.

    Recommended steps:

    • Review SELinux audit logs.
    • Restore the default security contexts.
    • Create a custom SELinux policy if required.
    • Use permissive mode only for troubleshooting purposes.

    AppArmor Blocking the Agent

    Issue:

    • Screen sharing or remote control does not function.
    • AppArmor denial messages appear in system logs.

    Possible causes:

    • AppArmor is restricting the Zoho Assist agent.

    Recommended steps:

    • Review AppArmor logs.
    • Place the Zoho Assist profile into complain mode.
    • Contact Zoho Assist Support if a custom AppArmor profile is required.

    Service Registration

    systemd Service Registration Failed

    Issue:

    • The installer cannot enable or start the unattended service.
    • The service is not registered.

    Possible causes:

    • The system is not using systemd.
    • systemd is running in a restricted environment.
    • The system partition is read only.

    Recommended steps:

    • Reload the systemd daemon.
    • Enable and start the unattended service.
    • Verify the service status.
    • If the device does not support systemd, use the appropriate init service.

    init.d Service Registration Failed

    Issue:
    Service registration fails on older Linux distributions.

    Possible causes:

    • Required init dependencies are missing.

    Recommended steps:

    • Install the required init packages and register the unattended service again.

    Unattended Service Files Missing

    Issue:
    The unattended service does not start after installation.

    Possible causes:

    • The installer package does not contain the unattended service components.

    Recommended steps:

    • Download and install the standard Zoho Assist installer.

    User Service Does Not Start

    Issue:
    Attended sessions work, but unattended sessions cannot access the desktop, clipboard, or audio.

    Possible causes:

    • User level systemd services are disabled.

    Recommended steps:

    • Enable lingering for the user account and restart the user service.

    Cron Service Not Available

    Issue:
    Scheduled maintenance tasks or log rotation do not run.

    Possible causes:

    • The cron service is not installed or is disabled.

    Recommended steps:

    • Install and enable the cron service, then retry the installation.

    Log Directory Cannot Be Created

    Issue:
    The agent starts but log files are not generated.

    Possible causes:

    • The log directory is read only.
    • The disk is full.
    • SELinux blocks write access.

    Recommended steps:

    • Create the required log directory.
    • Verify write permissions.
    • Ensure sufficient disk space is available.

    Missing Libraries and Dependencies

    Screen Sharing Libraries Missing

    Issue:
    Remote sessions connect successfully, but the technician sees a black or blank screen.

    Possible causes:

    • Required screen capture libraries are missing or outdated.

    Recommended steps:

    • Install the required screen capture and X11 libraries for your Linux distribution.

    GTK or UI Libraries Missing

    Issue:
    The system tray icon, confirmation dialog, or chat window does not appear.

    Possible causes:

    • GTK runtime libraries are missing.

    Recommended steps:

    • Install the required GTK and GLib packages.

    Audio Libraries Missing

    Issue:
    The session connects successfully, but remote audio is unavailable.

    Possible causes:

    • PulseAudio, PipeWire, or Opus runtime libraries are missing.

    Recommended steps:

    • Install the required audio libraries and verify that a default audio output device is configured.

    DBus Service Missing

    Issue:
    Clipboard sharing, lock screen detection, or active user detection does not function.

    Possible causes:

    • The DBus service is unavailable.

    Recommended steps:

    • Start and enable the DBus service.

    Architecture and Build Compatibility

    Exec Format Error

    Issue:
    The installer displays Cannot execute binary file.

    Possible causes:

    • The installer architecture does not match the operating system.

    Recommended steps:

    • Verify the system architecture and download the appropriate installer package.

    ARM Build Exits with Code 255

    Issue:
    The ARM installer completes successfully but the unattended service fails to start.

    Possible causes:

    • Missing bundled libraries.
    • Unsupported glibc version.

    Recommended steps:

    • Verify the installed glibc version and reinstall the appropriate ARM package.

    Distribution Specific Issues

    Raspberry Pi Does Not Display the Remote Screen

    Issue:
    The unattended service starts, but the remote screen is blank or extremely slow.

    Possible causes:

    • No display is connected.
    • No graphical desktop session is active.

    Recommended steps:

    • Connect a physical display or configure a dummy display.
    • Ensure a graphical desktop session is running before starting the unattended service.

    Wayland Session Detected

    Issue:
    The installer warns that unattended remote access is not supported while using Wayland.

    Possible causes:

    • The desktop environment is running under Wayland instead of X11.

    Recommended steps:

    • Configure the display manager to use X11 and sign in using an Xorg session before installing the unattended agent.

    Upgrade Leaves a Stale Process

    Issue:
    The updated unattended service fails to start because another instance is already running.

    Possible causes:

    • Processes from the previous installation were not terminated during the upgrade.

    Recommended steps:

    • Stop all Zoho Assist services, terminate any remaining processes, remove stale PID or lock files, and restart the unattended service.

    PREVIOUS

    UP NEXT