Blueprint convergence stuck in "pending/limbo" state due to APK file hash mismatch on managed app

Android

When a Blueprint is updated with a managed app whose APK upload was incomplete or interrupted, affected devices enter a perpetual pending convergence state and never reach Compliant — even though they appear online and connected.

Why this happens

Every APK stored in Esper has a calculated hash that the Esper Agent uses to verify the file it downloads matches the file you uploaded. If the upload was interrupted or the file was corrupted in transit, the stored hash does not match the actual file bytes. The Esper Agent downloads the file, fails validation, and retries indefinitely — stalling convergence for every device on that Blueprint.

Steps to resolve

1. Identify the blocking app.
   In the Esper Console, go to Devices & Groups → [Device Name] → Activity Feed and look for repeated install failure events referencing the same app. Note the exact app name and version number shown in the failure entries — this confirms which APK has the bad hash.
2. Obtain a verified copy of the APK.
   Download a fresh copy of the APK from its original source. Before uploading, confirm the file is complete by comparing its file size and SHA-256 checksum against the known-good values from the source. Uploading a second corrupted file will reproduce the same issue.
3. Upload the corrected APK to Esper.
   In the Esper Console, go to Apps & Configuration → Apps → [App Name] → Versions and upload the verified APK. Do not navigate away or close the browser tab until the upload progress bar reaches 100% and the console confirms the upload is complete — an interrupted upload will recreate the hash mismatch.
4. Update the Blueprint to reference the new version.
   Go to Blueprints → [Blueprint Name] → Apps, select the affected app, and choose the newly uploaded version from the version dropdown. Save the blueprint. This clears the reference to the corrupted APK and points all devices on this blueprint to the valid file.
5. Reboot each affected device to restart the convergence cycle.
   Go to Devices & Groups → [Device Name] → Actions and select Reboot. A reboot clears the stalled convergence state so the Esper Agent begins a fresh convergence attempt against the updated Blueprint. Repeat for every device that showed the pending state.

Verify: After the device comes back online, go to Devices & Groups → [Device Name] → Blueprint and confirm the convergence status changes to Compliant. Then go to Devices & Groups → [Device Name] → Apps and confirm the correct app version appears as installed. On a stable connection, convergence typically completes within 10 minutes of reboot.

If this doesn't resolve it

If the device remains stuck after completing all steps above, collect the following before contacting support:

• The device name and serial number
• The app name and both the failing version and the replacement version numbers
• Screenshots of the Activity Feed showing the repeated failure events
• Confirmation of whether multiple devices on the same Blueprint are affected
• Current status from status.esper.io — a CDN or app-delivery incident can produce identical symptoms across all devices on a Blueprint simultaneously

Contact Esper Support with this information and reference the Blueprint name and the affected app version.

---

Suggested title: Blueprint stuck in pending — APK hash mismatch on managed app

Still need help?

If your blueprint remains stuck in a pending state after verifying the APK file hash, submit a support ticket and include the blueprint name, the affected managed app name, and the APK hash values from both your source and the device.