Linux Esper Agent binaries corrupted to 0 bytes — manual recovery steps

Linux

When the Esper Agent self-update process is interrupted by an MQTT credential fetch failure on Linux, the agent binaries in /var/lib/esper/bin/ can be truncated to zero bytes, causing both agent services to stop and the device to go offline in the Esper Console.

Why this happens

During a self-update, the Esper Agent downloads new binaries and writes them in place. If an MQTT credential fetch fails mid-write, the file operation can terminate early, leaving the binary files at 0 bytes. Because both agent services depend on these binaries, neither can start, which also prevents any remote recovery through the Esper Console.

Before you begin

SSH or physical terminal access to the affected device is required. Once both agent services are down, the Esper Console cannot reach the device remotely, so all recovery steps must be performed locally or over an existing SSH session.

1. Confirm the binaries are corrupted. Connect to the device via SSH or a physical terminal and run:

   ls -la /var/lib/esper/bin/

   Zero-byte files confirm corruption. Healthy binaries are several megabytes each — a healthy output looks like this:

   -rwxr-xr-x 1 root root 13761096 Apr 26 22:17 cmse
   -rwxr-xr-x 1 root root  6356992 Apr 26 22:17 telemetry
   -rwxr-xr-x 1 root root  7995528 Apr 26 22:17 onp
   -rwxr-xr-x 1 root root  9635336 Apr 26 22:17 remote-desktop-helper

   If all files show 0 in the size column, continue to the next step.
2. Record the expected agent version. Read the manifest file so you can request or match the correct binaries:

   cat /var/lib/esper/bin/manifest.json

   Note the version number. If this file is also missing or unreadable, skip to the If this doesn't resolve it section below.
3. Obtain the correct replacement binaries. Use one of the following two options:
   • Copy from a working device: If another Linux device is enrolled with the same agent version, copy its /var/lib/esper/bin/ directory to a USB drive or transfer it securely to the affected device.
   • Request from Esper Support: Contact Esper Support and provide your device UUID, tenant name, and the agent version from manifest.json. Support will supply the correct binaries for your version.
4. Check for a read-only filesystem. Before copying files, confirm the filesystem is writable. If any subsequent write command returns a read-only filesystem error, remount it first:

   sudo mount -o remount,rw /

   This is only necessary if writes fail — skip this step if the filesystem is already writable.
5. Replace the corrupted binaries. Copy the recovered files into place, then restore the correct permissions and ownership:

   sudo cp /path/to/recovered/cmse /var/lib/esper/bin/cmse
   sudo cp /path/to/recovered/telemetry /var/lib/esper/bin/telemetry
   sudo cp /path/to/recovered/onp /var/lib/esper/bin/onp
   sudo cp /path/to/recovered/remote-desktop-helper /var/lib/esper/bin/remote-desktop-helper
   sudo chmod 755 /var/lib/esper/bin/cmse \
                  /var/lib/esper/bin/telemetry \
                  /var/lib/esper/bin/onp \
                  /var/lib/esper/bin/remote-desktop-helper
   sudo chown root:root /var/lib/esper/bin/*

   Setting permissions to 755 and owner to root:root matches the defaults the installer sets — without this the services may refuse to start.
6. Restart the Esper Agent services.

   sudo systemctl restart esper-cmse
   sudo systemctl restart esper-telemetry

7. Confirm both services are running.

   sudo systemctl status esper-cmse
   sudo systemctl status esper-telemetry

   Both should report active (running).

Verify: After both services show active (running), navigate to Devices & Groups → [Device Name] → Overview in the Esper Console. The device status should change to Online within 2–5 minutes.

If this doesn't resolve it

If the manifest.json file is missing, the binaries still show 0 bytes after replacement, or the services fail to reach active (running), contact Esper Support with the following information:

• Device UUID (visible in Devices & Groups → [Device Name] → Overview)
• Tenant name
• Device model and Linux distribution
• Output of sudo systemctl status esper-cmse and sudo systemctl status esper-telemetry
• Output of ls -la /var/lib/esper/bin/

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.