Device stuck in ONBOARDING state: factory reset or collect diagnostic logs

Android

When a device gets stuck in the ONBOARDING state, it never completes provisioning and does not appear as active in the Esper Console — leaving the device unusable and unmanaged.

Why this happens

During provisioning, the Esper Agent attempts to register the device with the Esper Console and apply its initial configuration. If the network connection drops, the provisioning payload is invalid, or the agent encounters an unrecoverable error mid-flow, the device stalls in ONBOARDING and cannot progress on its own.

Before you begin

• Confirm the device has a stable internet connection. Provisioning requires continuous connectivity to reach Esper's servers.
• If the device is completely unresponsive or stuck in a boot loop, skip to the hardware factory reset option below. The on-screen methods require a responsive touchscreen.
• If ten or more devices from the same batch are affected simultaneously, do not attempt individual resets — this likely indicates a platform-level provisioning issue. Go directly to If this doesn't resolve it.

Option 1: Factory reset using the Esper logo tap

Use this method first. It is the fastest path back to a provisionable state when the device screen is responsive and the Esper onboarding interface is visible.

1. Locate the Esper logo displayed on the device's onboarding screen.
2. Tap the Esper logo 6–7 times in quick succession. A Factory Reset option will appear on screen. This hidden tap sequence is an intentional recovery mechanism built into the Esper Agent.
3. Select Factory Reset. The device will wipe all data and reboot.
4. Re-provision the device using your standard method (QR code, Zero-Touch, KME, or your OEM's enrollment method).
5. In the Esper Console, navigate to Devices & Groups and confirm the device now appears with Active status.

If the Esper logo tap does not produce a Factory Reset option: the touchscreen may not be registering taps reliably, or the device is too unresponsive. Perform a hardware factory reset using your device's recovery mode instead (typically a power + volume button combination at boot). Consult your device manufacturer's documentation for the exact key sequence.

Option 2: Collect diagnostic logs before resetting

Use this method if you need to understand what caused the provisioning failure before wiping the device, or if Option 1 does not work. This requires a computer with ADB installed and USB access to the device.

1. Install ADB (Android Debug Bridge) on your computer if it is not already installed. ADB is part of the Android SDK Platform Tools, available from the Android developer site.
2. Enable USB debugging on the device. On most Android devices this is under Settings → Developer Options → USB Debugging.
3. Connect the device to your computer using a USB data cable (not a charge-only cable).
4. On the device screen, locate the Device ID shown on the Esper onboarding screen and tap it 5–6 times. The screen will display Fetching logs when the log collection has started. This confirms the log file is being written to device storage.
5. On your computer, run the following command to copy the log file locally:

   adb pull /storage/emulated/0/Download/dpc_logs.zip <your_local_path>

   • macOS example:

     adb pull /storage/emulated/0/Download/dpc_logs.zip ~/Desktop

   • Windows example:

     adb pull /storage/emulated/0/Download/dpc_logs.zip C:\Users\YourUsername\Desktop

6. After the log file is saved, proceed with a factory reset using Option 1 or a hardware recovery reset so the device can be re-provisioned.

Verify: After re-provisioning, the device should appear in Devices & Groups with a status of Active within 5 minutes. If it returns to ONBOARDING status again after the reset and re-provisioning attempt, do not repeat the reset — proceed to the section below.

If this doesn't resolve it

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

• The dpc_logs.zip file collected in Option 2, if available
• Your Esper Console enterprise name (visible in the Console URL)
• Device make, model, and Android version
• Provisioning method used (QR code, Zero-Touch, KME, or OEM)
• Number of devices affected and whether they came from the same device batch
• Whether the device has successfully provisioned before, or if this is a first-time enrollment

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.