Skip to content
Get started

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.

  • boot_is_good_on_shutdown (Optional, boolean): Whether an orderly shutdown (entering deep sleep, a restart or a shutdown) counts as a successful boot. When enabled, shutting down cleanly also confirms the running firmware on platforms with OTA bootloader rollback support, so the bootloader does not roll back a fresh OTA update. Set to false for strict rollback semantics: only boot_is_good_after elapsing or the safe_mode.mark_successful action confirms the firmware, so an update that goes back to sleep before proving itself healthy is still rolled back on the next wake. Defaults to true.

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

  • storage (Optional, string): Where to persist the boot-attempt counter. One of:

    • flash: store the counter in flash. It survives power loss but causes a small amount of flash wear on each boot.
    • rtc: store the counter in RTC memory. It survives software reboots (restarts, OTA updates, crashes) and deep sleep but not power loss, and avoids flash wear.

    Defaults to flash on ESP32 and rtc on ESP8266. Only flash is available on platforms without RTC-backed storage (the RP2040 and the ESP32-C2 and C61 variants, which have no RTC memory), where rtc is rejected.

    Note that on the original ESP32, pressing the hardware reset button (the EN pin) also clears RTC memory, so it counts as power loss rather than as a reboot. On newer variants (S3, C3, C6) RTC memory survives a chip reset triggered over USB. Safe mode itself is unaffected either way: crash loops always consist of software resets, which RTC memory survives on all variants.

  • 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

On platforms with OTA bootloader rollback support enabled (see enable_ota_rollback for ESP32 and nRF52), marking the boot as successful also confirms the currently running firmware, so the bootloader does not roll back to the previous version after an OTA update.

NOTE

Since ESPHome 2026.8.0, an orderly shutdown — entering deep sleep, a restart or a shutdown — automatically marks the boot as successful and confirms the firmware, so devices that sleep before boot_is_good_after elapses no longer need to run this action to keep OTA updates from being rolled back. This can be disabled with the boot_is_good_on_shutdown option, in which case only boot_is_good_after elapsing or this action confirms the firmware. See Deep Sleep and OTA Rollback for details.

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”