UPDATE_WIFI_AP command fails on active network: use staged ADD/REMOVE/ADD approach

Android

The UPDATE_WIFI_AP command fails with an "Unsupported" error when you attempt to change the password of the Wi-Fi network your device is currently connected to. This article explains why this happens and shows you two ways to resolve it.

Why UPDATE_WIFI_AP fails on your active network

The UPDATE_WIFI_AP command cannot directly modify the credentials of a network your device is actively using. Changing the password while the device is connected can cause the network profile to fail and disconnect the device. To protect against this, certain versions of the Esper Agent reject the command as unsupported.

This issue is most common if your Esper Agent version is below 10.0.3256 or if agent auto-updates are locked at your tenant.

Option 1: Use staged network migration (works on all agent versions)

The safest approach is to migrate your device to a temporary backup network, update the primary network profile, then reconnect. Follow these steps:

1. Add a temporary backup network so your device has a fallback connection:

   curl -s -X POST "https://<tenant>-api.esper.cloud/api/commands/v0/commands/" \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
    "command_type": "DEVICE",
    "devices": ["<device_id>"],
    "device_type": "all",
    "command": "ADD_WIFI_AP",
    "command_args": {
    "wifi_ssid": "<backup-ssid>",
    "wifi_password": "<backup-password>",
    "wifi_security_type": "WPA2",
    "hidden": false
    }
    }'

2. Verify your device connects to the backup network. In the Esper Console, go to Devices & Groups → [Device Name] → Device Info → Network and confirm the device is now connected to the backup SSID.
3. Remove the primary network profile (your device is no longer actively on it):

   curl -s -X POST "https://<tenant>-api.esper.cloud/api/commands/v0/commands/" \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
    "command_type": "DEVICE",
    "devices": ["<device_id>"],
    "device_type": "all",
    "command": "REMOVE_WIFI_AP",
    "command_args": {
    "wifi_ssid": "<primary-ssid>"
    }
    }'

4. Re-add the primary network with the new password:

   curl -s -X POST "https://<tenant>-api.esper.cloud/api/commands/v0/commands/" \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
    "command_type": "DEVICE",
    "devices": ["<device_id>"],
    "device_type": "all",
    "command": "ADD_WIFI_AP",
    "command_args": {
    "wifi_ssid": "<primary-ssid>",
    "wifi_password": "<new-password>",
    "wifi_security_type": "WPA2",
    "hidden": false
    }
    }'

5. Wait for your device to reconnect to the primary network with the updated credentials.
6. Optional: Remove the backup network once your device is stable on the primary network by sending another REMOVE_WIFI_AP command targeting the backup SSID.
7. Verify success: In the Esper Console, go to Devices & Groups → [Device Name] → Device Info → Network and confirm your device is connected to the primary SSID. Then check Devices & Groups → [Device Name] → Commands and verify all command statuses show Success.

Option 2: Update Esper Agent to version 10.0.3256 or later

If agent auto-updates are locked at your tenant, you can request a backend deployment of the latest agent version, then deploy it to your devices via a pipeline. This is the preferred long-term fix.

1. Contact Esper Support and request backend deployment of Esper Agent version 10.0.3256 or later to your tenant.
2. Once the agent version is available, deploy it to your devices. Follow the Deploying Esper Software Updates guide to create and push a deployment pipeline.
3. After devices are updated, retry the UPDATE_WIFI_AP command. It should now succeed.
4. Verify success: Check the command status in Devices & Groups → [Device Name] → Commands and confirm your device remains connected to the updated network in Device Info → Network.

Troubleshooting

If the staged ADD/REMOVE/ADD migration fails:

• Check whether a Blueprint policy is blocking new Wi-Fi profile additions. Review your device's active policy in Devices & Groups → [Device Name] → Policies.
• Verify your device is online and the Esper Agent is running by checking Devices & Groups → [Device Name] → Device Info → Agent Version.

If ADD_WIFI_AP returns an error:

• Confirm your device is online and has an active network connection.
• Verify the Esper Agent is running on the device.
• Check that the SSID, password, and security type are correct in your command payload.

Still need help?

If the staged network migration and agent update options above do not resolve the issue, or if you encounter an error code not covered here, submit a support ticket and include:

• Your device ID and device model
• Your current Esper Agent version
• The full error response from the command
• The exact SSID and network configuration you are trying to update