An ESP32 watchdog reset is not one diagnosis. ESP-IDF has separate watchdog paths for blocked interrupts, tasks that fail to yield and supervision during startup or low-power operation. The panic reason identifies which execution guarantee was broken, so read it before increasing any timeout.
The two messages most application developers encounter are Interrupt wdt timeout on CPU0 or CPU1, and Task watchdog got triggered. They point to different mechanisms. One means a CPU could not service its FreeRTOS tick in time; the other means a watched task or idle task did not run within the configured period.
Interrupt watchdog: the tick could not run
The interrupt watchdog timer, or IWDT, uses the main-system watchdog in Timer Group 1. ESP-IDF feeds it from the FreeRTOS tick interrupt on each CPU. If the tick does not execute before the timeout, something has blocked interrupts on that core.
Common causes are a long critical section, interrupts disabled around too much work, or a same- or higher-priority interrupt service routine that does not return. ESP-IDF recommends keeping critical sections and ISRs short, moving noncritical computation outside them, and using a queue to defer ISR work to a task. An ISR or critical section should not block while waiting for another event.
The IWDT is enabled by CONFIG_ESP_INT_WDT, and CONFIG_ESP_INT_WDT_TIMEOUT_MS sets its period. Espressif states that the timeout should be more than twice the interval between FreeRTOS ticks. If ticks are 10 ms apart, the timeout should therefore exceed 20 ms. That relationship prevents the watchdog from expiring merely because its period is too close to the scheduler’s normal cadence.
Task watchdog: a task or idle task was starved
The task watchdog timer, or TWDT, uses the main-system watchdog in Timer Group 0. By default, it watches the idle task on each CPU. A compute loop, peripheral poll or other task that runs for too long without yielding prevents the idle task from executing and triggers the watchdog.
The timeout report lists the tasks or users that did not reset the watchdog and shows which tasks were running on each CPU. Preserve that log and backtrace. It is stronger evidence than the final reset alone because it identifies the core and execution path active when progress stopped.
Code should normally fix the scheduling problem: break long work into bounded pieces, call a blocking FreeRTOS primitive instead of spin-polling, or insert a deliberate yield where latency allows. For explicit monitoring, esp_task_wdt_add() subscribes a task and esp_task_wdt_reset() feeds it. The user API—esp_task_wdt_add_user() and esp_task_wdt_reset_user()—can monitor a specific code path rather than a whole task.
CONFIG_ESP_TASK_WDT_TIMEOUT_S sets the default TWDT period. The default response is a warning and backtrace while the application continues; CONFIG_ESP_TASK_WDT_PANIC changes that response to a panic and system reset. Long flash erases are a documented case that may need a temporary timeout adjustment, but extending the period should follow evidence that the long operation is expected and bounded.
RTC watchdog and boot-time resets
The RTC/LP watchdog covers boot-time and low-power-domain behavior. ESP-IDF normally disables the RTC watchdog immediately before the application’s main function. If CONFIG_BOOTLOADER_WDT_DISABLE_IN_USER_CODE keeps it active, application code must feed or disable it in time. A reset during boot can also point to an invalid second-stage bootloader or communication trouble with external flash.
Do not confuse watchdog resets with brownouts. A power droop can reset the chip without a task-starvation backtrace; capturing the supply rail during the event separates voltage collapse from a software liveness fault.
A debugger can hide the fault
JTAG changes watchdog behavior. ESP-IDF documentation says OpenOCD disables the interrupt and task watchdog hardware timers at every breakpoint and does not re-enable them after execution resumes. A program that runs indefinitely under a halted debugger can still reset in production because the safety mechanism was absent during the debug session.
Reproduce the failure once without breakpoints, retain the complete panic reason and backtrace, and map the address information to the matching firmware build. Then inspect the smallest responsible path: interrupt-disabled time for IWDT, yield and blocking behavior for TWDT, or startup feed/disable logic for RTC_WDT.
A larger timeout can be valid when the worst-case operation is intentional, measured and still compatible with the system’s recovery requirement. It is not a substitute for identifying why a core stopped making progress. The useful result is not merely a board that resets less often; it is a bounded execution path and a watchdog period chosen from that bound.
