Provisioning hangs mid-setup: pin stable Esper Agent version

Android

If your devices are hanging during provisioning, the issue may be related to an unstable Esper Agent version being used during setup. This article walks you through pinning a stable Agent version to resolve provisioning hangs.

Understand the problem

Devices may hang at various points during provisioning—such as Step 1 or during app installation—when an unstable or mismatched Esper Agent version is being applied. This can happen across multiple device models and persists through factory resets.

The root cause is typically that the provisioning process uses the Esper Agent version that's already on the device, rather than the latest version available. If the "Default Provisioning Version" is set to automatically select the latest build and that build contains a regression, your devices will provision with the problematic agent and hang.

Before you begin

You'll need access to the Esper Console to update the default provisioning version. Make sure you have the device serial numbers of the affected devices.

Step 1: Pin a stable Esper Agent version

1. Open the Esper Console.
2. Navigate to Esper Esper Software Updates → Esper Agent → Default Provisioning Version.
3. If automatic or "latest" version selection is enabled, disable it.
4. Manually select a known stable Esper Agent version (for example, 13.0.4449).
5. Save your changes.

Step 2: Factory reset the affected device

Choose one of the following methods:

• Option 1: Factory reset via standard Android recovery.
• Option 2: On the provisioning screen, tap the Esper logo 6–7 times to surface the in-device reset option, then select Factory Reset.

Step 3: Re-provision the device

1. Re-provision your device using your existing QR code or provisioning method.
2. Allow provisioning to complete fully without interruption. The device will come online with the pinned agent version.
3. After provisioning completes, the newer agent version will be available as an over-the-air (OTA) update, which the device can install post-onboarding.

Step 4: Verify the device is provisioned

1. In the Esper Console, navigate to Devices & Groups → [Device Name].
2. Confirm the device appears as Online and fully provisioned.
3. Check that the agent version shown matches the pinned version you selected (for example, 13.0.4449).
4. Verify the device is no longer stuck on any setup screen.

Troubleshooting

Device still hangs after pinning a stable version:

• Pull device logs from the Esper Console by navigating to Devices & Groups → [Device Name] → Logs, or via ADB using adb logcat. These logs will show the exact point where provisioning fails.
• Confirm whether provisioning is actually complete from the backend—sometimes the device UI may appear stuck while provisioning has actually succeeded in the backend.
• If the agent version on the device differs from the version you pinned in the Esper Console, or if the hang persists across multiple devices or device models, contact Esper Support with your device serial numbers and tenant ID.

About agent version mismatches:

It is normal behavior for the device to run an older agent version than the one selected in the Esper Console immediately after provisioning. The provisioning flow uses the agent already present on the device and upgrades to the newer version post-onboarding rather than during setup.

Still need help?

If you've followed these steps and your devices are still experiencing issues, submit a support ticket. include your device serial numbers, tenant ID, and the agent version you pinned.