# 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.

ESP_RETURN_ON_ERROR_CLEANUP(x, ...)

  Evaluate an esp_err_t expression, run cleanup on error, and return.

  Evaluates `x` once and stores the result in a local variable `err_rc_`. If the result is not ESP_OK, the macro:

  - executes the code passed in `__VA_ARGS__` (e.g., cleanup functions or logging),

  - returns `err_rc_` from the current function. The cleanup code can freely use `err_rc_`.

  Example:

      esp_err_t initialize_device(void)
      {
      // Simple case: single cleanup action
          ESP_RETURN_ON_ERROR_CLEANUP(open_device("/dev/adc0"), close_device());

      // Multiple cleanup actions
          ESP_RETURN_ON_ERROR_CLEANUP(
              allocate_buffer(4096),
              free_buffer(),
              close_device(),
              printf("Failed to initialize sensor: %s\n", esp_err_to_name(err_rc_))
          );

      // Complex cleanup with conditional logic and ESP_LOG logging
          ESP_RETURN_ON_ERROR_CLEANUP(
              calibrate_sensor(),
      do {
      if (err_rc_ == ESP_ERR_INVALID_STATE) {
                     ESP_LOGE(TAG, "Sensor in invalid state during calibration");}
                  }
                  free_buffer();
                  close_device();
                  ESP_LOGE(TAG, "Drop connection");
              } while (0)
          );

      return ESP_OK;
      }

### 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.