Remote Viewer session stuck in "starting session" state and fails with `Remote viewer disconnected` error

Android

When starting a Remote Viewer session from the Esper Console, the session becomes stuck on "Starting session" and then fails with a Remote viewer disconnected error.

Why this happens

The Remote Viewer feature relies on a persistent WebSocket connection between your browser, the Esper platform, and the Esper Agent running on the device. This connection can be blocked or dropped by corporate firewalls, VPN clients, or network proxies that restrict WebSocket traffic. In some cases, a misconfigured user account or a missing Supervisor plugin on the device can also prevent the session from establishing.

Before you begin

Work through the steps below in order. Each step isolates a different potential cause. Stop as soon as a session connects successfully — the step that fixes it identifies the root cause.

1. Rule out client-side network interference. Connect your laptop and the affected device to the same mobile hotspot (for example, an iPhone personal hotspot), then navigate to Devices & Groups → [Device Name] → Remote Viewer and attempt a session. Using a hotspot removes corporate network restrictions from the equation. If the session connects, your corporate network is the cause — skip to step 3.
2. Rule out VPN interference. Confirm no VPN client is active on your laptop. If one is running, disconnect it. Navigate to Devices & Groups → [Device Name] → Remote Viewer and attempt the session again. VPN clients frequently intercept or terminate WebSocket connections required by Remote Viewer.
3. Rule out corporate firewall restrictions. Attempt the session from outside your corporate network — for example, from a home network or mobile hotspot. If this succeeds, work with your network team to confirm that your firewall permits outbound traffic to all required Esper endpoints and ports. For the full list of required endpoints, refer to Esper network requirements.
4. Rule out account or permission issues. Navigate to Account Settings → Users and remove your user account. Have an account administrator send you a fresh invitation, accept it, and log back in to the Esper Console. Then navigate to Devices & Groups → [Device Name] → Remote Viewer and attempt the session. Corrupted or partially provisioned user accounts can silently prevent session establishment.
5. Verify the Supervisor plugin status on the device. Navigate to Devices & Groups → [Device Name] and review the device details panel. Confirm that the Supervisor plugin is listed and shows as active. If the plugin is missing or inactive, Remote Viewer cannot complete the handshake with the device. Contact Esper Support if the plugin is absent, as remediation depends on your device model and provisioning method.
6. Collect a browser HAR trace for further diagnosis. If the session still fails after steps 1–5, capture a network trace to identify exactly where the connection breaks.
   1. Open your browser's developer tools and go to the Network tab.
   2. Navigate to Devices & Groups → [Device Name] → Remote Viewer and attempt the session.
   3. Wait for the Remote viewer disconnected error to appear.
   4. Right-click anywhere in the Network tab and select Save all as HAR with content. Save the file to your computer.
7. Collect device logs via ADB. Connect the affected device to your computer via USB, then run the following command in a terminal or command prompt:

   adb shell logcat -d > esper_agent_logs.txt

   This saves the full Esper Agent log output to esper_agent_logs.txt in your current directory. These logs allow Esper Support to trace exactly where the Remote Viewer handshake fails on the device side.

Verify: A successful Remote Viewer session displays a live screen feed of the device within approximately 15 seconds of clicking Start Session. The "Starting session" spinner resolves and the Remote viewer disconnected error does not appear.

If this doesn't resolve it

Contact Esper Support and include the following information so the issue can be diagnosed without back-and-forth:

• Your device model and firmware version (visible under Devices & Groups → [Device Name] → Device Info)
• The Esper Agent version installed on the device
• Which steps above you completed and what each attempt returned
• The HAR file captured in step 6
• The ADB log file captured in step 7
• Whether the issue affects a single device or multiple devices in your fleet

Still need help?

If the steps above don't resolve the issue, submit a support ticket with your device model, Android version, Esper Agent version, and a description of what you've already tried — this helps the support team investigate without a follow-up.