Troubleshooting Unattended Access Connection Issues on macOS Remote Device

    This guide is for unattended access sessions. It helps you resolve errors you may encounter when setting up or running an unattended access session on a Mac. Each section covers an issue along with its possible causes and recommended steps.

    Agent Installation

    Agent installation unsuccessful

    Issue:
    After installing the unattended agent on the Mac, the device does not appear in the Zoho Assist console.

    Possible causes:

    • The installation did not complete successfully.
    • The installer was not run with administrator privileges.
    • macOS security settings blocked the installation.

    Recommended steps:

    • Re-run the installer and provide the administrator password when prompted.
    • If macOS displays a security warning, download the installer directly from the Zoho Assist website and re-run it.
    • If the issue persists, uninstall the agent completely and perform a fresh installation.

    Device appears as "Offline" in the console

    Issue:
    The remote Mac shows as offline in the Zoho Assist console, even though the device is powered on.

    Possible causes:

    • The device is not connected to the internet.
    • The Zoho Assist background service is not running on the device.
    • A firewall or network restriction is blocking the agent from reaching Zoho Assist servers.

    Recommended steps:

    • Verify that the remote device is powered on and connected to the internet.
    • Open Activity Monitor on the remote device and check if the ZohoPingAgent process is running.
    • If the process is not running, execute the following command in Terminal:
      sudo launchctl load /Library/LaunchDaemons/com.zoho.assist.zohoUnattended.plist
    • If the device is behind a corporate firewall or proxy, ensure connections to *.zohoassist.com on port 443 are allowed.
    • If the device uses a proxy, configure the proxy settings within the Zoho Assist agent.

    Setup

    "Permission Required" window appears when the session starts

    Issue:
    When connecting to a Mac running macOS Mojave (10.14) or later, Zoho Assist requires Accessibility and Screen Recording permissions to function. If these haven't been granted, a permission prompt appears on the remote device.

    • Without Accessibility permission, the technician cannot control the mouse or keyboard.
    • Without Screen Recording permission, the technician will see a black or blank screen.

    Recommended steps:

    • In the permission window, click Proceed to view the two permission options.
    • Click Configure next to Accessibility, then enable Zoho Assist in the system dialog.
    • Click Configure next to Screen Recording, then enable Zoho Assist in the system dialog.
    • Once both permissions are granted (indicated by blue checkmarks), click Proceed to continue.

    Note for MDM-managed devices: A PPPC (Privacy Preferences Policy Control) profile can be deployed to pre-approve these permissions across devices, eliminating the need for manual action on each one.

    In-Session Issues

    Black or blank screen after connecting

    Issue:
    The technician connects successfully but sees only a black, grey, or blank screen.

    Possible causes:

    • Screen Recording permission has not been granted or was revoked.
    • The remote Mac is a laptop with its lid closed and no external display connected.

    Recommended steps:

    • On the remote device, go to System Settings > Privacy & Security > Screen Recording and confirm Zoho Assist is enabled.
    • If the Mac is a laptop with the lid closed, open the lid or connect an external display.
    • Click Refresh in the technician viewer to request a fresh screen image.

    Cannot control mouse or keyboard on the remote device

    Issue:
    The technician can view the remote screen, but mouse and keyboard inputs have no effect.

    Possible causes:

    • Accessibility permission has not been granted or was revoked.

    Recommended steps:

    • On the remote device, go to System Settings > Privacy & Security > Accessibility and confirm Zoho Assist is enabled.
    • Once the permission is granted, remote control resumes automatically — no reconnection needed.

    Session keeps disconnecting and reconnecting

    Issue:
    The remote session drops frequently, causing intermittent connectivity for the technician.

    Possible causes:

    • Unstable or slow internet connection on the remote device.
    • A corporate firewall or proxy terminating long-lived connections.

    Recommended steps:

    • Check that the remote device has a stable Wi-Fi or wired Ethernet connection.
    • If the device is behind a corporate firewall or proxy, confirm that WebSocket connections to Zoho Assist servers are not being blocked.
    • Try switching between Wi-Fi and a wired connection to isolate the issue.
    • If the problem continues, disconnect and start a new session.

    "Network Error" window appears on the remote device

    Issue:
    A network error dialog appears on the remote Mac and the session cannot continue.

    Possible causes:

    • The internet connection on the remote device was lost.
    • The connection to Zoho Assist servers could not be re-established after multiple retries.
    • Proxy settings are incorrectly configured.

    Recommended steps:

    • Verify that the remote device has an active internet connection.
    • If the device uses a proxy, confirm the proxy settings (IP address, port, and credentials) are correctly configured in the agent.
    • Close the error window to end the current session.
    • Once the network issue is resolved, reconnect from the Zoho Assist console.

    Session ended due to network error

    Issue:
    The session terminates unexpectedly with a message indicating a network error occurred.

    Possible causes:

    • The remote device lost its internet connection during the session.
    • All connection retry attempts were exhausted.

    Recommended steps:

    • Ensure the remote device's internet connection is restored.
    • Start a new session from the Zoho Assist console.
    • If this happens repeatedly, check for network instability or restrictive firewall rules on the remote device's network.

    Frozen or unresponsive screen

    Issue:
    The technician sees a static image of the remote screen that does not update.

    Possible causes:

    • A slow network connection is delaying screen updates.
    • The agent temporarily paused screen sharing due to network congestion.

    Recommended steps:

    • Click Refresh in the technician viewer to request a fresh screen image.
    • Lower the image quality setting in the viewer to reduce bandwidth usage.
    • Check the internet speed on both the technician and remote device ends.
    • If the screen remains frozen, disconnect and reconnect to the session.

    Device does not reconnect after a remote reboot

    Issue:
    The technician initiated a reboot on the remote device, but the session did not resume after the device restarted.

    Possible causes:

    • The session expired before the device finished restarting.

    Recommended steps:

    • Wait a few minutes after the reboot for the device to fully start up and for the agent to reconnect.
    • Refresh the Devices page in the Zoho Assist console to check the device status.
    • If the device shows as online but the session has not resumed, start a new session.

    Increased latency or poor performance

    Issue:
    The remote session is slow, with noticeable delays between actions and screen updates.

    Possible causes:

    • Slow internet connection on either end.
    • High network latency between the technician and the remote device.

    Recommended steps:

    • Lower the image quality in the technician viewer to reduce bandwidth requirements.
    • Close unnecessary applications on the remote device that may be consuming bandwidth.
    • If possible, switch to a faster or wired internet connection on both ends.

    PREVIOUS

    UP NEXT