Device provisioning stalls or fails to complete: gathering diagnostic data to unblock investigation

Android

When a device stalls or fails to complete provisioning, it stops responding at some point in the setup flow — such as during QR code scanning, Esper Agent download, Device Owner assignment, or Blueprint application — and never comes online in the Esper Console.

Why this happens

Provisioning failures almost always trace back to one of three root causes: the device cannot reach Esper's endpoints due to network or firewall restrictions; the provisioning template is inactive, misconfigured, or references an invalid Blueprint; or the device's firmware is incompatible with the provisioning method being used. Pinpointing the exact failure point before collecting logs saves significant diagnostic time.

Before you start

Gather the following before working through the steps below:

Physical access to at least one affected device, or an active ADB connection to it
The provisioning method used: QR code, Zero-Touch Enrollment (ZTE), Knox Mobile Enrollment (KME), or ADB
Access to your Esper Console

Steps

Identify the exact point where provisioning stops. Work through the provisioning flow and note the last screen the device reaches before stalling or erroring. The most common failure points are:
- QR code scan — device does not recognize or process the code
- Esper Agent download — the agent APK fails to download or install
- Device Owner setup — the device does not grant Device Owner rights
- Blueprint application — the device receives the Blueprint but does not apply it
- First boot — the device reboots but never appears online in the Esper Console
Knowing the failure point determines which logs and settings to examine next.
Capture all on-screen error messages. Take a screenshot or screen recording of every error dialog, stuck screen, or system prompt blocking progress. Note the full text of any error codes or messages — for example DEVICE_OWNER_SETUP_FAILED — so they can be matched against known issues.
Pull provisioning logs via ADB. Connect the device to a workstation with ADB enabled and run:
```
adb shell logcat -d | grep -iE "esper|device_owner|provisioning"
```
Save the full output to a text file. These logs show exactly where the provisioning sequence breaks and why.
Request a bug report from the Esper Console if the device is partially enrolled. If the device is visible in the Console — even in an incomplete state — navigate to Devices & Groups → [Device Name] → Actions, then select Request Bug Report. Download the report once it generates. A Console-side bug report captures agent-level detail that ADB logcat may not include.
Verify your provisioning template. In the Esper Console, go to Provisioning → Provisioning Templates and open the template associated with the affected devices. Confirm:
- The template status is Active
- The template references a valid, published Blueprint
- The correct provisioning method (QR code, ZTE, KME, or ADB) is selected
An inactive template or a reference to a deleted Blueprint will silently block provisioning completion. Correct any issues and retry.
Confirm the device can reach Esper's network endpoints. Provisioning requires uninterrupted outbound HTTPS access. On the device or network, verify:
- The device has an active Wi-Fi or cellular connection
- Your firewall or proxy is not blocking Esper's provisioning endpoints — check the current allowlist in the Esper firewall requirements documentation
- Captive portals or certificate inspection proxies are not intercepting Esper traffic

Verify: After correcting the identified issue and reprovisioning, the device should appear in Devices & Groups with a status of Active within 10 minutes. The Activity Feed for that device will show a successful enrollment event confirming the Blueprint was applied.

If this doesn't resolve it

If the device is still failing to provision after completing the steps above, contact Esper Support with the following information:

Device make, model, and Android OS version
Provisioning method used
The exact screen or step where provisioning stops
Screenshots or screen recordings of any error messages
ADB logcat output from step 3
Bug report from the Esper Console, if the device was partially enrolled (step 4)
Name of the provisioning template used

Still need help?

If device provisioning continues to stall or fail after trying these steps, please submit a support ticket and include the diagnostic data collected from your device logs, provisioning timeline, and any error messages displayed during the provisioning process.