Possible cause Solution Description
The buffer size is set too small and the download speed is low. Therefore, the download times out and an over-the-air (OTA) update fails.

Check the value of the AIOT_DLOPT_BODY_BUFFER_MAX_LEN parameter in the aiot_download_setopt operation. Increase the parameter value and reinitiate an OTA update.

In a Linux environment, we recommend that you set this value to 2 KB.

AIOT_DLOPT_BODY_BUFFER_MAX_LEN specifies the size of the buffer that is used to receive firmware-related messages.

A notification is sent to the device when the downloaded firmware fully occupies the buffer. You can reduce the number of notifications and shorten the download duration by increasing the buffer size. If the buffer size is too small, the download is time-consuming and prone to network jitter.

In a multithreading system, a slow download task occupies the CPU and affects the normal operation of other business.

The timeout period of an OTA update is set too short. Increase the value of the Device upgrade time-out (minutes) parameter when you initiate an update task. For more information, see Initiate a batch update.

Set the parameter value based on your business requirements. You must consider the effect of network jitter.

If the value is set too small and the device does not complete the update and submit a new version number within the specified period, IoT Platform determines that the update fails and closes the download channel.

The destination devices do not exist when you set the OTA update scope to Selected Devices. Log on to the IoT Platform console and check the version numbers of the specified devices. For more information, see View update status.

If the version numbers of the devices do not match the version number to be updated, submit the version numbers again and reinitiate an OTA update.

Check whether the devices to be updated have submitted the version numbers.
  • No: Submit the version numbers of the devices.
  • Yes: Check whether the submitted version numbers are valid. If not, submit the version numbers again.
The device submits the 100% update progress by calling the aiot_download_report_progress operation, but IoT Platform determines that the OTA update fails. After the OTA update is completed, call the aiot_ota_report_version operation to submit the latest version number. IoT Platform determines whether an OTA update is successful based on the submitted version number rather than the firmware download percentage.
The segmentation settings are invalid when you configure a segmented download. Reset the parameters that are related to the segmented download. For more information, see Example. When you configure a segmented download, make sure that segments are downloaded from beginning to end, and no overlaps exist between segments.

For example, if you set the following segments: [0, 1024] and [1024, 2048], the 1024th byte is downloaded twice. In this case, the download fails. You must change it to [0, 1024] and [1025, 2048].

A network error occurs. Check the network connection. Try again after the network connection is restored.

If the network connection is ended during the download, the device cannot receive messages. The following example shows a common error message: 

download failed, error code is -3864, try to send renewal request