QR Code Provisioning Stalls on Black Screen After Android Native Dialogs Complete

Android

If your device shows a black screen after scanning a QR code and accepting Android setup dialogs, and provisioning does not complete, follow these steps to resolve the issue.

Before you begin

Ensure you have:

Access to the Esper Console
The device's serial number or Esper device code
A stable Wi-Fi connection available for the device
ADB (Android Debug Bridge) installed on your computer, if needed for diagnostics

Step 1: Remove the stale device record from the Esper Console

In the Esper Console, navigate to Devices & Groups → All Devices.
Locate the affected device by its serial number or Esper device code.
If the device shows as Offline, click Actions → Wipe & Remove.
If wipe commands are not reaching the device, select Remove Only instead.
Confirm the device no longer appears in the Esper Console before proceeding to the next step.

Step 2: Factory reset the device

Perform a hardware factory reset rather than a software reset to remove any remaining Esper Agent remnants:

Power off the device completely.
Hold Power + Volume Down (or your device's OEM-equivalent key combination) until the recovery menu appears.
Select Wipe data / factory reset from the menu.
Confirm the reset and allow the device to reboot.

Step 3: Verify network connectivity

Before re-provisioning, ensure the device has proper network access:

Connect the device to a stable Wi-Fi network with unrestricted outbound HTTPS access.
Verify the device can reach Esper endpoints. Avoid captive portals or networks requiring proxy authentication during provisioning.
If you are behind a corporate firewall, confirm that outbound traffic to *.esper.io and Google MDM infrastructure is not blocked.

Step 4: Generate a fresh QR code

In the Esper Console, navigate to Provisioning Templates → [Your Template Name] → QR Code.
Generate or download a new QR code to ensure the provisioning token is valid.

Step 5: Reprovision the device

On the factory-reset device, scan the fresh QR code using the device camera or QR code reader.
Accept all Android native setup dialogs that appear.
Wait for the Esper enrollment screen to appear. The device should display the Esper loading or enrollment UI after the native dialogs complete.
Complete the enrollment process.

Step 6: Verify successful enrollment

In the Esper Console, navigate to Devices & Groups.
Confirm the device appears with status Online.
Verify that your assigned Blueprint is shown as applied.

If the black screen persists

If the issue continues after a clean factory reset and fresh QR code, try the following:

Try an alternative provisioning method

Attempt provisioning using a different enrollment method to rule out a QR code–specific issue:

Zero-Touch Enrollment (if your device supports it)
Knox Mobile Enrollment (KME) (for Samsung devices)

Collect diagnostic logs

Connect the device to your computer via USB cable and enable ADB debugging.

After the black screen appears, run the following command to capture device logs:

adb logcat -s AndroidRuntime:E DPCReceiver:* EsperDeviceOwner:* > provisioning_log.txt

Check that the Esper Esper Agent package is installed:
```
adb shell pm list packages | grep esper
```
Save these logs and include them when contacting Esper Support.

Force-remove the device using the API

If the device cannot be removed from the Esper Console using the standard method:

Use the Esper API to retrieve the device ID:

GET /v0/enterprise/{enterprise_id}/device/?device_name=[device_serial]

Delete the device record:

DELETE /v0/enterprise/{enterprise_id}/device/{device_id}/

Attempt reprovisioning with a fresh QR code.

Still need help?

If you continue to experience issues after trying these steps, contact Esper Support. include:

Your device serial number
The device model and Android version
The provisioning logs collected via ADB (if available)
A description of any error messages shown on the device