Skip to content
ESPHome - Smart Home Made Simple 2026.5.0

Safe Mode

Sometimes hardware and/or software doesn’t behave as expected. ESPHome supports a “safe mode” to help recover from repeated boot failures/reboot loops. After a specified number (the default is ten) of boot failures, the safe mode may be invoked; in this mode, all components are disabled except serial logging, network (Wi-Fi or Ethernet) and the OTA component(s). In most cases, this will temporarily mitigate the issue, allowing you a chance to correct it, perhaps by uploading a new binary.

You can also force the invocation of safe mode by configuring a dedicated button or switch component and/or by repeatedly pressing the reset button on the board for num_attempts times (see below).

# Example configuration entry
safe_mode:

Configuration variables

Section titled “Configuration variables”

  • disabled (Optional, boolean): Set to true to disable safe_mode. Ota automatically sets up safe mode; this allows disabling it if/when it is not wanted.

  • boot_is_good_after (Optional, Time): The amount of time after which the boot is considered successful. Defaults to 1min.

  • num_attempts (Optional, int): The number of failed boot attempts which must occur before invoking safe mode. Defaults to 10.

  • reboot_timeout (Optional, Time): The amount of time to wait before rebooting when in safe mode. Defaults to 5min.

  • on_safe_mode (Optional, Automation): An action to be performed once when safe mode is invoked.

WARNING

The on_safe_mode automation is intended for use by recovery actions only.

As mentioned above, in safe mode, all components are disabled except serial logging, network (Wi-Fi or Ethernet) and OTA component(s).

All other components (for example, displays and sensors) are disabled and cannot be used.

safe_mode.mark_successful Action

Section titled “safe_mode.mark_successful Action”

This action marks the boot as successful, preventing safe mode from being invoked. This is useful for devices that take a sensor reading and then enter deep sleep, rather than waiting for the boot_is_good_after time to elapse.

on_...:
  then:
    - safe_mode.mark_successful

Rebooting to the recovery app on ESP32

Section titled “Rebooting to the recovery app on ESP32”

If safe_mode detects that OTA updates are impossible because of the partition layout on the device, the message OTA updates are impossible will appear in the config section of the logs, followed by the suggested next step.

In case a valid recovery app is found but OTA is impossible with the current app, invoking safe mode will automatically reboot to it. Depending on the recovery app’s features this can allow you to install an OTA update and recover your soft-bricked device. The recovery app can for example be a previous version of ESPHome or the Tasmota safeboot app. It is recommended to update the partition table while recovering your device to make future OTA updates possible.

See Also

Section titled “See Also”