ESP-IDF Programming Guide Choose target... Choose version... Get Started API Reference Hardware Reference API Guides Security Guides Migration Guides Libraries and Frameworks Contributions Guide ESP-IDF Versions Resources Copyrights and Licenses About Switch Between Languages ESP-IDF Programming Guide ESP-IDF Programming Guide Edit on GitHub ESP-IDF Programming Guide [中文] This is the documentation for Espressif IoT Development Framework (esp-idf). ESP-IDF is the official development framework for the ESP32, ESP32-S, ESP32-C, ESP32-H and ESP32-P Series SoCs. This document describes using ESP-IDF with the ESP32-C6 SoC. To switch to a different SoC target, choose target from the dropdown in the upper left. Get Started API Reference API Guides Was this page helpful? Thank you! We received your feedback. If you have any comments, fill in Espressif Documentation Feedback Form. We value your feedback. Let us know how we can improve this page by filling in Espressif Documentation Feedback Form. Next © Copyright 2016 - 2026, Espressif Systems (Shanghai) Co., Ltd. Built with Sphinx using a theme based on Read the Docs Sphinx Theme. Download HTML ESP-IDF Programming Guide Choose target... Choose version... Get Started API Reference API Conventions Application Protocols Bluetooth® API Error Codes Reference Networking APIs Peripherals API Provisioning API Storage API System API App Image Format Bootloader Image Format Application Level Tracing Call Function with External Stack Chip Revision Console eFuse Manager Error Code and Helper Functions API Reference ESP HTTPS OTA Event Loop Library FreeRTOS Overview FreeRTOS (IDF) FreeRTOS (Supplemental Features) Heap Memory Allocation Memory Management for MMU Supported Memory Heap Memory Debugging ESP Timer (High Resolution Timer) Internal and Unstable APIs Interrupt Allocation Logging library Miscellaneous System APIs Over The Air Updates (OTA) Power Management POSIX Support (Including POSIX Threads Support) Random Number Generation Sleep Modes SoC Capability Macros System Time Asynchronous Memory Copy Ultra Low Power (ULP) coprocessor Watchdogs Configuration Options Reference Hardware Reference API Guides Security Guides Migration Guides Libraries and Frameworks Contributions Guide ESP-IDF Versions Resources Copyrights and Licenses About Switch Between Languages ESP-IDF Programming Guide API Reference System API Error Code and Helper Functions Edit on GitHub Error Code and Helper Functions [中文] This section lists definitions of common ESP-IDF error codes and several helper functions related to error handling. For general information about error codes in ESP-IDF, see Error Handling. For the full list of error codes defined in ESP-IDF, see Error Codes Reference. API Reference Header File components/esp_common/include/esp_check.h This header file can be included with: #include "esp_check.h" Macros ESP_RETURN_ON_ERROR(x, log_tag, format, ...) Macro which can be used to check the error code. If the code is not ESP_OK, it prints the message and returns. In the future, we want to switch to C++20. We also want to become compatible with clang. Hence, we provide two versions of the following macros. The first one is using the GNU extension ##__VA_ARGS__. The second one is using the C++20 feature VA_OPT(,). This allows users to compile their code with standard C++20 enabled instead of the GNU extension. Below C++20, we haven't found any good alternative to using ##__VA_ARGS__. Macro which can be used to check the error code. If the code is not ESP_OK, it prints the message and returns. ESP_RETURN_ON_ERROR_ISR(x, log_tag, format, ...) A version of ESP_RETURN_ON_ERROR() macro that can be called from ISR. ESP_RETURN_VOID_ON_ERROR(x, log_tag, format, ...) Macro which can be used to check the error code. If the code is not ESP_OK, it prints the message and returns. This macro is used when the function returns void. ESP_RETURN_VOID_ON_ERROR_ISR(x, log_tag, format, ...) A version of ESP_RETURN_VOID_ON_ERROR() macro that can be called from ISR. ESP_GOTO_ON_ERROR(x, goto_tag, log_tag, format, ...) Macro which can be used to check the error code. If the code is not ESP_OK, it prints the message, sets the local variable 'ret' to the code, and then exits by jumping to 'goto_tag'. ESP_GOTO_ON_ERROR_ISR(x, goto_tag, log_tag, format, ...) A version of ESP_GOTO_ON_ERROR() macro that can be called from ISR. ESP_RETURN_ON_FALSE(a, err_code, log_tag, format, ...) Macro which can be used to check the condition. If the condition is not 'true', it prints the message and returns with the supplied 'err_code'. ESP_RETURN_ON_FALSE_ISR(a, err_code, log_tag, format, ...) A version of ESP_RETURN_ON_FALSE() macro that can be called from ISR. ESP_RETURN_VOID_ON_FALSE(a, log_tag, format, ...) Macro which can be used to check the condition. If the condition is not 'true', it prints the message and returns without a value. ESP_RETURN_VOID_ON_FALSE_ISR(a, log_tag, format, ...) A version of ESP_RETURN_VOID_ON_FALSE() macro that can be called from ISR. ESP_GOTO_ON_FALSE(a, err_code, goto_tag, log_tag, format, ...) Macro which can be used to check the condition. If the condition is not 'true', it prints the message, sets the local variable 'ret' to the supplied 'err_code', and then exits by jumping to 'goto_tag'. ESP_GOTO_ON_FALSE_ISR(a, err_code, goto_tag, log_tag, format, ...) A version of ESP_GOTO_ON_FALSE() macro that can be called from ISR. Header File components/esp_common/include/esp_err.h This header file can be included with: #include "esp_err.h" Functions const char *esp_err_to_name(esp_err_t code) Returns string for esp_err_t error codes. This function finds the error code in a pre-generated lookup-table and returns its string representation. The function is generated by the Python script tools/gen_esp_err_to_name.py which should be run each time an esp_err_t error is modified, created or removed from the IDF project. Parameters: code -- esp_err_t error code Returns: string error message const char *esp_err_to_name_r(esp_err_t code, char *buf, size_t buflen) Returns string for esp_err_t and system error codes. This function finds the error code in a pre-generated lookup-table of esp_err_t errors and returns its string representation. If the error code is not found then it is attempted to be found among system errors. The function is generated by the Python script tools/gen_esp_err_to_name.py which should be run each time an esp_err_t error is modified, created or removed from the IDF project. Parameters: code -- esp_err_t error code buf -- [out] buffer where the error message should be written buflen -- Size of buffer buf. At most buflen bytes are written into the buf buffer (including the terminating null byte). Returns: buf containing the string error message Macros ESP_OK esp_err_t value indicating success (no error) ESP_FAIL Generic esp_err_t code indicating failure ESP_ERR_NO_MEM Out of memory ESP_ERR_INVALID_ARG Invalid argument ESP_ERR_INVALID_STATE Invalid state ESP_ERR_INVALID_SIZE Invalid size ESP_ERR_NOT_FOUND Requested resource not found ESP_ERR_NOT_SUPPORTED Operation or feature not supported ESP_ERR_TIMEOUT Operation timed out ESP_ERR_INVALID_RESPONSE Received response was invalid ESP_ERR_INVALID_CRC CRC or checksum was invalid ESP_ERR_INVALID_VERSION Version was invalid ESP_ERR_INVALID_MAC MAC address was invalid ESP_ERR_NOT_FINISHED Operation has not fully completed ESP_ERR_NOT_ALLOWED Operation is not allowed ESP_ERR_WIFI_BASE Starting number of WiFi error codes ESP_ERR_MESH_BASE Starting number of MESH error codes ESP_ERR_FLASH_BASE Starting number of flash error codes ESP_ERR_HW_CRYPTO_BASE Starting number of HW cryptography module error codes ESP_ERR_MEMPROT_BASE Starting number of Memory Protection API error codes ESP_ERROR_CHECK(x) Macro which can be used to check the error code, and terminate the program in case the code is not ESP_OK. Prints the error code, error location, and the failed statement to serial output. Disabled if assertions are disabled. ESP_ERROR_CHECK_WITHOUT_ABORT(x) Macro which can be used to check the error code. Prints the error code, error location, and the failed statement to serial output. In comparison with ESP_ERROR_CHECK(), this prints the same error message but isn't terminating the program. Type Definitions typedef int esp_err_t Was this page helpful? Thank you! We received your feedback. If you have any comments, fill in Espressif Documentation Feedback Form. We value your feedback. Let us know how we can improve this page by filling in Espressif Documentation Feedback Form. Previous Next © Copyright 2016 - 2026, Espressif Systems (Shanghai) Co., Ltd. Built with Sphinx using a theme based on Read the Docs Sphinx Theme. Download HTML ESP-IDF Programming Guide Choose target... Choose version... Get Started API Reference Hardware Reference API Guides Security Guides Migration Guides ESP-IDF 5.x Migration Guide Migration from 4.4 to 5.0 Migration from 5.0 to 5.1 Migration from 5.1 to 5.2 Migration from 5.2 to 5.3 Migration from 5.3 to 5.4 Migration from 5.4 to 5.5 Build System Security System Peripherals Protocols Wi-Fi ESP-IDF 6.x Migration Guide Libraries and Frameworks Contributions Guide ESP-IDF Versions Resources Copyrights and Licenses About Switch Between Languages ESP-IDF Programming Guide Migration Guides Migration from 5.4 to 5.5 Security Edit on GitHub Security [中文] Mbed TLS Starting from ESP-IDF v5.5, there is a change in how the SHA sub-function APIs, esp_sha_block() and esp_sha_dma(), are used. Previously, these APIs used to set the SHA mode internally, however, in the updated version, you must explicitly set the SHA mode before invoking them. For instance, if you intend to use the SHA-256 algorithm, you must first call esp_sha_set_mode() with the argument SHA2_256: esp_sha_set_mode(SHA2_256); Was this page helpful? Thank you! We received your feedback. If you have any comments, fill in Espressif Documentation Feedback Form. We value your feed