Detecting and Fixing FreeRTOS Stack Overflow on ESP32

What causes this

Stack overflow in FreeRTOS occurs when a task exceeds its allocated stack memory. This often results in unpredictable behavior or system crashes. On the ESP32, stack overflow detection is facilitated by the FreeRTOS kernel, which can be configured to check for overflows at context switch times. When a stack overflow is detected, the vApplicationStackOverflowHook() function is called. The most common causes include:

• Incorrect stack size allocation during task creation.
• Deep or infinite recursion within a task.
• Large local variable declarations, especially arrays or structs.
• Improper use of dynamic memory allocation leading to fragmentation.

When a stack overflow occurs, the ESP32 may output an error like:

```

Guru Meditation Error: Core 0 panic'ed (Unhandled debug exception)

Debug exception reason: Stack canary watchpoint triggered (TaskName)

```

This is often accompanied by a stack trace or backtrace, which can be analyzed to pinpoint the issue.

Minimal reproduction

To reproduce a stack overflow, consider the following minimal code snippet:

```c

#include

#include

void vOverflowTask(void *pvParameters) {

char largeArray[1024]; // Large array leading to overflow

for (;;) {

// Simulate work

}

}

void app_main() {

xTaskCreate(&vOverflowTask, "OverflowTask", 1024, NULL, 1, NULL);

}

```

With this setup, the stack size is insufficient for the largeArray, leading to:

```

Guru Meditation Error: Core 0 panic'ed (Unhandled debug exception)

Debug exception reason: Stack canary watchpoint triggered (OverflowTask)

Backtrace: 0x4008c3d0:0x3ffbff20 0x4008c55d:0x3ffbff40

```

The fix

To resolve this issue, increase the stack size during task creation. Here is the corrected code:

Before:

```c

xTaskCreate(&vOverflowTask, "OverflowTask", 1024, NULL, 1, NULL);

```

After:

```c

xTaskCreate(&vOverflowTask, "OverflowTask", 2048, NULL, 1, NULL);

```

This ensures that the task has sufficient stack space for its operations. Always balance stack size with available memory resources.

How SerialDoctor catches this

SerialDoctor connects to your ESP32 via Web Serial and rapidly diagnoses issues like stack overflow. It reads the serial output, identifies the tell-tale signs of a stack overflow, such as the "Stack canary watchpoint triggered" message, and provides an instant, detailed analysis of the root cause. With SerialDoctor, you get actionable insights in under 3 seconds, allowing you to focus on fixing the problem. Visit [serialdoctor.com](https://www.serialdoctor.com) to learn more.

Quick checklist

• [ ] Ensure each task has adequate stack size by reviewing task requirements.
• [ ] Regularly check and minimize local variable sizes within tasks.
• [ ] Use vApplicationStackOverflowHook() to catch stack overflows early.
• [ ] Monitor serial output for "Stack canary watchpoint triggered" messages.
• [ ] Utilize tools like SerialDoctor for rapid diagnosis and debugging.

Seeing this crash on your board right now?

Connect it to SerialDoctor and get a root cause + code fix in under 3 seconds.