Chapter 4. API Guides
Common errors and known issues
• dfu-util: command not found might indicate that the tool hasn’t been installed or is not available
from the terminal. An easy way of checking the tool is running dfu-util --version. Please see Step
1. Install prerequisites for installing dfu-util.
• The reason for No DFU capable USB device available could be that the USB driver wasn’t
properly installed on Windows (see USB drivers (Windows only)), udev rule was not setup on Linux (see udev
rule (Linux only)) or the device isn’t in bootloader mode.
• Flashing with dfu-util on Windows fails on the first attempt with error Lost device after RESET?.
Please retry the flashing and it should succeed the next time.
4.7 Error Handling
4.7.1 Overview
Identifying and handling run-time errors is important for developing robust applications. There can be multiple kinds
of run-time errors:
• Recoverable errors:
– Errors indicated by functions through return values (error codes)
– C++ exceptions, thrown using throw keyword
• Unrecoverable (fatal) errors:
– Failed assertions (using assert macro and equivalent methods, see Assertions) and abort() calls.
– CPU exceptions: access to protected regions of memory, illegal instruction, etc.
– System level checks: watchdog timeout, cache access error, stack overflow, stack smashing, heap corrup-
tion, etc.
This guide explains ESP-IDF error handling mechanisms related to recoverable errors, and provides some common
error handling patterns.
For instructions on diagnosing unrecoverable errors, see Fatal Errors.
4.7.2 Error codes
The majority of ESP-IDF-specific functions use esp_err_t type to return error codes. esp_err_t is a signed
integer type. Success (no error) is indicated with ESP_OK code, which is defined as zero.
Various ESP-IDF header files define possible error codes using preprocessor defines. Usually these defines start
with ESP_ERR_ prefix. Common error codes for generic failures (out of memory, timeout, invalid argument, etc.)
are defined in esp_err.h file. Various components in ESP-IDF may define additional error codes for specific
situations.
For the complete list of error codes, see Error Code Reference.
4.7.3 Converting error codes to error messages
For each error code defined in ESP-IDF components, esp_err_t value can be converted to an error code
name using esp_err_to_name() or esp_err_to_name_r() functions. For example, passing 0x101 to
esp_err_to_name() will return “ESP_ERR_NO_MEM”string. Such strings can be used in log output to
make it easier to understand which error has happened.
Additionally, esp_err_to_name_r() function will attempt to interpret the error code as a standard POSIX error
code, if no matching ESP_ERR_ value is found. This is done using strerror_r function. POSIX error codes
(such as ENOENT, ENOMEM) are defined in errno.h and are typically obtained from errno variable. In ESP-IDF
this variable is thread-local: multiple FreeRTOS tasks have their own copies of errno. Functions which set errno
only modify its value for the task they run in.
Espressif Systems 1303
Submit Document Feedback
Release v4.4
To Next Page
Loading...
Need help?
General