Troubleshooting Unattended Agent Installation Issues on macOS Devices

    Zoho Assist installation may fail after successful download and extraction due to the following causes:

    • Account not authorized or not a member of the organization
    • License limit exceeded or invalid authentication key
    • Antivirus or security software blocking installation
    • Insufficient disk space or unsupported macOS version
    • Previous Zoho Assist installation interfering with new installation

    Use the steps below to identify the cause and complete the installation.

    Prerequisites

    Check the following before troubleshooting:

    • The device has a stable internet connection.
    • The installer or deployment link was shared by your Zoho Assist administrator.
    • The device meets the macOS 10.15 or later requirements (Learn more about supported operating system requirements).
    • Antivirus, firewall, or endpoint security tools are not blocking the installer.

    Account & Authorization Issues

    Issue: Not a Member of This Organization

    Possible Cause:
    Your account is not associated with the organization that created the deployment link or authentication key.

    Recommended Steps:

    • Confirm that you are using the correct Zoho Assist organization account.
    • Check whether your email address has been added to the organization.
    • Complete email verification if prompted.
    • Contact your Zoho Assist administrator and ask them to verify:
      • Organization membership
      • Technician role or deployment permissions
      • Department access
    • Try installing the agent again after the required access is granted.

    Issue: Deployment Permission Denied

    Possible Cause:
    Your account does not have permission to deploy unattended agents in the organization.

    Recommended Steps:

    • Contact your Zoho Assist administrator.
    • Ask them to grant you deployment permissions.

    Issue: No Access to Department

    Possible Cause:
    You are trying to install the agent under a department you do not have access to.

    Recommended Steps:

    • Contact your Zoho Assist administrator.
    • Request access to the required department.

    Network & Connectivity Issues

    You may see errors such as:

    • Cannot connect to server / Unable to connect to server / Cannot reach Zoho Servers
    • Connection failed / Network connection failed
    • The installation hangs or times out

    Possible Cause:
    The installer is unable to reach Zoho Assist servers. This may happen due to an unstable internet connection, firewall restrictions, proxy settings, or network security policies.

    Recommended Steps:

    • Open a web browser on the affected device.
    • Visit https://assist.zoho.com and verify the page loads.
    • If the page doesn't load, restore internet connectivity before trying to connect again.
    • If you are on a corporate network, ask your IT team to allow Zoho Assist traffic.
    • Ensure HTTPS traffic over port 443 is allowed.
    • If your organization uses a proxy, verify proxy settings are configured correctly.
    • Try the installation again.

    License & Quota Issues

    Issue: License Limit Exceeded

    Possible Cause:
    The organization has reached the maximum number of unattended devices allowed by the current Zoho Assist subscription.

    Recommended Steps:

    • Contact your Zoho Assist administrator and ask them to check the available unattended access license count.
    • Remove inactive or unused devices from the Zoho Assist portal if required.
    • Upgrade the subscription plan if more unattended devices are needed.

    Issue: Invalid Authentication Token or Expired Authentication Key

    Possible Cause:
    The deployment link or authentication key is no longer valid for the selected department or organization.

    Recommended Steps:

    • Confirm the deployment link is intended for the correct organization and department.
    • Avoid using old installer files or previously downloaded deployment packages.
    • Download the latest installer from your administrator and try the installation again.

    You may see error messages such as:

    • "Deployment link expired"
    • "Invalid deployment link"
    • "Link has been deactivated"

    Possible Cause:

    • Deployment link or authentication key has expired or is no longer valid.
    • Link has been deactivated by the admin.

    Recommended Steps:

    • Check with your admin if the link has been intentionally deactivated. If so, request a new deployment link and try again.

    Issue: Department Configuration Inactive

    Possible Cause:
    The department you're trying to install to has been deactivated.

    Recommended Steps:

    • Contact your org admin to request activation of the department, or use a deployment link for an active department instead.

    Endpoint Security & Gatekeeper Issues

    Issue: Installer Blocked by Gatekeeper

    You may see errors such as:

    • "Cannot be opened because Apple cannot check it for malicious software"
    • The installer does not open.

    Possible Cause:
    macOS Gatekeeper blocks the installer because it cannot verify the developer signature.

    Recommended Steps:

    • Open System Settings (or System Preferences on older macOS).
    • Go to Privacy & Security.
    • Scroll down to the Security section and click Open Anyway next to the blocked installer.
    • Confirm when prompted.
    • Retry the installation.
    • If the device is MDM-managed, ask your IT administrator to approve the installer policy.

    Issue: Endpoint Security or Antivirus Blocking Installation

    You may see errors such as:

    • The installation stops suddenly.
    • Installation files disappear after extraction.
    • The Zoho Assist service fails to start.

    Possible Cause:
    Antivirus or endpoint protection software is blocking the installer or extracted files.

    Recommended Steps:

    • Open your antivirus or endpoint security application.
    • Check the quarantine or blocked items list.
    • Look for files related to "Zoho".
    • Restore the files (only if downloaded from a trusted Zoho Assist deployment link).
    • Add the following to your security tool's allowed list:
      • /Library/Application Support/ZohoAssist/
    • Try installing the agent again.

    For centrally managed endpoint security:

    • Contact your IT security team to allow/whitelist Zoho Assist before retrying.

    Issue: Missing Privacy Permissions (TCC)

    You may see symptoms such as:

    • Agent installed but the remote screen appears black.
    • Keyboard or mouse control fails during remote session.

    Possible Cause:
    Required macOS privacy permissions have not been granted to Zoho Assist.

    Recommended Steps:

    • Open System Settings.
    • Go to Privacy & Security.
    • Grant the following permissions to Zoho Assist:
      • Screen Recording
      • Accessibility
    • Restart the Zoho Assist agent after granting permissions.

    Issue: LaunchDaemon / Service Not Running

    You may see symptoms such as:

    • Installation completes but the device appears offline in the Zoho Assist portal.
    • The unattended agent service is not running.

    Possible Cause:
    The launchd plist was not loaded, was blocked, or the service crashed during startup.

    Recommended Steps:

    • Reboot the device and check if the device appears online.
    • Open Terminal and verify the service using launchctl.
    • If the service is missing, reinstall using the latest installer package.

    Issue: Previous Installation Detected

    Possible Cause:
    Files or services from an earlier Zoho Assist installation are interfering with the new installation.

    Recommended Steps:

    • Open Finder, go to Applications, and look for Zoho Assist Unattended.
    • Uninstall existing Zoho components and remove all residual files.
    • Restart the device.
    • Run the latest installer again.

    System Requirements & Compatibility

    Issue: Unsupported or Outdated macOS Version

    Possible Cause:
    The macOS version does not meet the minimum requirements for installing the Zoho Assist unattended agent.

    Recommended Steps:

    • Open the Apple menu and go to About This Mac to check the installed macOS version.
    • Install the latest available macOS updates via System Settings > General > Software Update.
    • If the OS is no longer supported by Apple, upgrade to a supported macOS version.
    • Try the installation again.

    Supported versions: macOS 10.15 (Catalina) and later.

    Issue: Installer Package is Outdated or Corrupted

    Possible Cause:
    The installer file is outdated, corrupted, or no longer valid.

    Recommended Steps:

    • Delete the old installer file.
    • Request a fresh deployment link from your Zoho Assist admin, or download the latest installer.
    • Run the installation again.

    Note: Don't use installer files older than 6 months.

    If you've tried the troubleshooting steps above and the issue persists, please contact us at support@zohoassist.com.

    PREVIOUS

    UP NEXT