Device stuck in ONBOARDING state: factory reset via Esper logo tap or ADB log collection to diagnose provisioning failure

Android

When a device gets stuck in the ONBOARDING state, it fails to complete provisioning and never appears as active in the Esper Console.

Why this happens

During provisioning, the Esper Agent attempts to register the device with your Esper Console and apply its assigned Blueprint. If network connectivity drops, the provisioning configuration is invalid or expired, or the agent encounters an unrecoverable error mid-setup, the device stalls in the ONBOARDING state and cannot proceed on its own.

Before you begin

• Confirm the device has active internet connectivity. A Wi-Fi or mobile data connection is required to complete provisioning.
• If the device is in a boot loop or the screen is completely unresponsive, a hardware factory reset through the device's recovery mode is required instead. Consult your device manufacturer's documentation for the correct recovery mode key combination.
• If ten or more devices from the same batch are affected simultaneously, skip to If this doesn't resolve it — this pattern typically indicates a platform-level provisioning issue that requires investigation.

Option 1: Factory reset using the Esper logo tap

Use this method first if the device screen is responsive and the Esper onboarding interface is visible.

1. Locate the Esper logo 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 tap sequence is a built-in recovery shortcut in the Esper Agent that is intentionally undocumented on-screen to prevent accidental resets.
3. Select Factory Reset to wipe the device and trigger a reboot.
4. Re-provision the device using your standard method (QR code, Zero-Touch, KME, or your OEM's provisioning method).
5. In the Esper Console, go to Devices & Groups and confirm the device now appears with an Active status rather than ONBOARDING.

Verify: The device should appear as Active in Devices & Groups within 5 minutes of completing re-provisioning.

Option 2: Collect diagnostic logs via ADB

Use this method if the logo tap does not produce a Factory Reset option, or if you need to diagnose the root cause before resetting the device.

1. Install ADB (Android Debug Bridge) on your computer. ADB is available as part of the Android SDK Platform Tools.
2. Enable USB debugging on the device. On most Android devices this is found under Settings → About Phone (tap Build Number seven times to unlock Developer Options), then 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's onboarding screen, tap the Device ID displayed on screen 5–6 times until the message Fetching logs appears. This triggers the Esper Agent to write a diagnostic bundle to device storage.
5. On your computer, run the following command to pull the log bundle:

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

   For example:
   • macOS:

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

   • Windows:

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

6. Save the dpc_logs.zip file — it contains the provisioning error details needed to diagnose the failure.

Verify: The dpc_logs.zip file is present on your computer at the path you specified.

Troubleshooting

• The logo tap did not show a Factory Reset option: Perform a hardware factory reset using the device's recovery mode. Consult your device manufacturer's documentation for the correct key combination (typically a Power + Volume button sequence).
• The Device ID is not visible on screen: Skip Option 1 and Option 2 and proceed directly to a hardware factory reset via recovery mode.
• The device is still stuck in ONBOARDING after factory reset and re-provisioning: The provisioning configuration loaded by your OEM at manufacture time may be invalid or expired. Collect the dpc_logs.zip file using Option 2 and contact Esper Support with the log file and your device model and batch details.

If this doesn't resolve it

Contact Esper Support and include the following:

• The dpc_logs.zip file collected in Option 2
• The device model, Android version, and OEM name
• The number of devices affected and whether they are from the same batch or order
• A screenshot of the ONBOARDING state as shown in Devices & Groups in the Esper Console
• The provisioning method used (QR code, Zero-Touch, KME, or OEM-specific)

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.