Blueprint Converge fails on device with outdated Esper Agent (v7): update agent to resolve stuck state

Android

If a device is stuck during a Blueprint Converge operation after being migrated from Templates, it's likely running an outdated Esper Agent version that doesn't support Converge. Follow these steps to update your agent and complete the migration.

Before you begin

This issue occurs when you're migrating a device from the legacy Templates system to Blueprints using a Converge command, but the device is running Esper Agent v7 or earlier. Devices in this state may appear as Registered (offline) instead of Active, and the Converge operation will not complete.

Step 1: Check your device's Esper Agent version

1. In the Esper Console, go to Devices & Groups → [Device Name] → Device Details.
2. Locate the Esper Agent version field.
3. If the version is v7 or below, you need to update the agent before proceeding with Converge.

Step 2: Verify the device is set to Active

1. In Devices & Groups → [Device Name], check the device's current state.
2. If the device shows as Registered or inactive, you may need to set it to Active before continuing. If the option is not available in the Esper Console, contact Esper Support.

Step 3: Update the Esper Agent

1. In the Esper Console, navigate to Devices & Groups → [Device Name].
2. Select the option to update the Esper Agent to the latest version.
3. The update command will be sent immediately if the device is online. If the device is offline, the command will enter a Pending state and will execute automatically when the device reconnects.

Step 4: Bring the device online

Make sure the device is connected to the network so the agent update command can process. If the device is at a remote location, coordinate with your on-site staff to power cycle and reconnect it if needed.

Step 5: Re-issue the Converge command

1. Once the agent has updated successfully, go to Devices & Groups → [Device Name] → Blueprint.
2. Send the Converge command again.
3. Wait for the device to process the command and transition to Active state.

Step 6: Verify the migration is complete

1. Confirm the device now shows as Active in the Esper Console.
2. Verify the Blueprint is displayed as applied on the device details page.
3. Test that the device behaves as expected under the new Blueprint configuration.

If Converge still fails after the agent update

• Collect device logs: Go to Devices & Groups → [Device Name] → Device Logs to retrieve logs. Alternatively, you can pull logs via ADB with the command: adb shell logcat -d | grep -i "esper\|Esper Agent\|converge". Look for error messages related to the Converge attempt.
• Device remains offline: If the device cannot be brought online remotely, ensure on-site staff can perform a power cycle and network reconnection.
• Agent update command stays pending: If the device is confirmed to be online but the update command remains in Pending state, contact Esper Support.
• Converge command fails repeatedly: Contact Esper Support and provide the device serial number and any error logs you've collected.

Important notes about Templates-to-Blueprints migration

• Always verify your device is running Esper Agent v8 or later before initiating a Converge operation.
• Devices provisioned with the legacy Templates system may not display clear error messages on-screen if the Converge fails, especially if the device is at a remote location.
• Esper queues commands for offline devices automatically. When you send an update or Converge command, you do not need to re-issue it—simply bring the device online and the command will execute.

Still need help?

If you've followed these steps and your device is still stuck or the Converge operation continues to fail, submit a support ticket. Include your device serial number, current Esper Agent version, and any error logs you've collected.