I've been building Ava, a personal desk gadget on a Waveshare ESP32-S3 1.75" round AMOLED board, using Meta's open source Muse Gadgets SDK. The SDK gives you the firmware for pairing, a Bluetooth companion, a display UI and a session with the Muse backend, and you bring the hardware.
Everything worked, until the gadget hit its first token refresh. Then it crashed and rebooted. Every time.
No memory corruption, no null pointer, nothing in my own code. The cause was which kind of RAM a single task's stack lived in. It's an easy one to miss on any ESP32 with PSRAM, so here's the whole story.
The symptom
- The gadget pairs, connects and runs fine.
- When its session token needs refreshing, it asserts and reboots.
- The assert fires in
esp_task_stack_is_sane_cache_disabled(), deep inside ESP-IDF's flash code.
That function name is the clue. It's ESP-IDF checking that the current task's stack is usable while the flash cache is disabled.
Background: why a flash write cares about your stack
On an ESP32-S3 there are two kinds of RAM:
- Internal SRAM: small (a few hundred KB) and always accessible.
- PSRAM: external, large (8 MB on this board), and accessed through the same cache as flash.
Writing to flash, which includes saving anything to NVS (the key-value store), temporarily disables that cache. While it's off, anything that lives in PSRAM is unreachable, including the stack of the task that's doing the write.
So ESP-IDF checks before every flash operation. If your task's stack is in PSRAM and the cache is about to go away, it asserts rather than let the CPU read garbage from its own stack. (Boards that also run code and read-only data from PSRAM can keep the cache on during writes, and the check passes. This board's build doesn't.)
The root cause: a helper that saves RAM, used by the wrong task
Internal RAM is precious on these boards. The SDK has a small helper for short-lived tasks like pairing timers, Wi-Fi scan refresh and provisioning, and on boards that opt in it puts their stacks in PSRAM:
static inline BaseType_t helper_task_create(TaskFunction_t fn, const char *name,
uint32_t stack_bytes, void *arg,
UBaseType_t priority, TaskHandle_t *out)
{
#if HELPER_TASK_STACK_IN_PSRAM
return xTaskCreateWithCaps(fn, name, stack_bytes, arg, priority, out,
MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT);
#else
return xTaskCreate(fn, name, stack_bytes, arg, priority, out);
#endif
}
That's a good trick for tasks that never touch flash. The task that fetches the backend session, muse_vm, was created with it:
if (helper_task_create(hatch_vm_task, "muse_vm", 8192, &req, 4, NULL) != pdPASS) {
return false;
}
And muse_vm does touch flash: when it refreshes the token, it saves the new one to NVS. The NVS write disabled the cache, the cache took the stack with it, and ESP-IDF asserted. (The SDK's own header actually warns about this. The crash came from a task that broke the rule.)
Fix, part 1: put that task's stack back in internal RAM
The fix itself is one line: create muse_vm with plain xTaskCreate, which allocates the stack from internal RAM.
if (xTaskCreate(hatch_vm_task, "muse_vm", 8192, &req, 4, NULL) != pdPASS) {
ESP_LOGE(TAG, "muse_vm task not created: internal RAM %uK free, largest block %uK",
(unsigned)(heap_caps_get_free_size(MALLOC_CAP_INTERNAL) / 1024),
(unsigned)(heap_caps_get_largest_free_block(MALLOC_CAP_INTERNAL) / 1024));
return false;
}
Two details matter here:
-
The task must now end with
vTaskDelete(NULL), not the helper's delete. A task createdWithCapshas to be freed by the matchingWithCapsdelete. Mixing the two leaks the stack and the task control block, or worse. - Log the heap when creation fails. "Task not created" tells you nothing. Free internal RAM and the largest free block tell you whether you're out of memory or just fragmented, and on these boards that difference is the whole problem.
Which brings me to part 2.
Fix, part 2: there was no 8 KB block left
With the stack back in internal RAM, muse_vm needed one contiguous 8 KB block of it. On my board there wasn't one.
The reason was Bluetooth. The SDK starts the NimBLE stack at boot on most boards, because the BLE controller needs its own large internal block (around 30 KB) and it's easiest to grab that before TLS and the backend session fragment the heap. On the 1.75C, NimBLE at boot plus everything else left no 8 KB hole for muse_vm.
The SDK already had an answer for a similar board: on the CrowPanel, and upstream on the non-C version of this board, BLE starts lazily, only when it's needed. I did the same for the 1.75C:
#if CONFIG_MUSE_ENABLED && CONFIG_SPIRAM && !CONFIG_MUSE_BOARD_CROWPANEL_ADVANCE_43 && \
!CONFIG_MUSE_BOARD_WAVESHARE_S3_175C
// ... bring the BLE stack up at boot ...
// The CrowPanel starts it lazily instead. So does the 1.75C:
// the idle stack leaves no 8 KB block for the muse_vm task.
start_ble_setup_server_if_needed();
#endif
muse_vm got its 8 KB, and the token refresh stopped crashing.
Fix, part 3: lazy start broke "forget all paired phones"
Changing when a subsystem starts usually breaks something that assumed it was already running. Here it was "forget all paired phones". Simplified, the original looked like this:
void muse_ble_forget_all(void)
{
if (muse_link_ble_started()) {
ble_store_clear();
return;
}
// stack not up: nothing happened, and the bonds were still in NVS
}
With BLE no longer started at boot, ble_store_clear() often had nothing to clear. NimBLE keeps bonds persisted in NVS and loads them again whenever the stack starts. So the user tapped "forget", nothing was deleted, and the next time Bluetooth came up, the "forgotten" phones were paired again. That's a privacy bug, not just a UX one.
The fix has two halves.
When the stack is down, delete the bonds where they're actually stored:
#define NIMBLE_BOND_NS "nimble_bond"
s_forget_pending = true;
nvs_handle_t h;
esp_err_t err = nvs_open(NIMBLE_BOND_NS, NVS_READWRITE, &h);
if (err == ESP_OK) {
err = nvs_erase_all(h);
if (err == ESP_OK) err = nvs_commit(h);
nvs_close(h);
}
Then close the race. If the stack happened to be starting while "forget" ran, it may already have loaded the old bonds into memory. So a flag makes the first connection after a forget clear the store again, before the link can encrypt with an old bond:
case BLE_GAP_EVENT_CONNECT:
if (ev->connect.status == 0) {
if (s_forget_pending) {
s_forget_pending = false;
ble_store_clear();
}
// ...
}
What I took away from it
- On ESP32, "where is this task's stack?" is a real question. PSRAM stacks save internal RAM, but any task that writes flash or NVS needs an internal stack, unless your build keeps the cache on during writes.
- When an allocation fails, log free memory and the largest free block. Fragmentation hides behind a healthy free-memory number.
- When you make a subsystem start lazily, audit everything that assumed it was running. "Forget paired devices" is exactly the kind of rarely tested path that breaks quietly.
- Read the SDK's own headers. The rule that caused this crash was written right there in a comment. I found it after the backtrace, not before.
The fix was 43 lines across two files. Finding why a flash write crashed meant understanding how the cache, PSRAM and NVS interact on this chip, and that's knowledge I'll use on every ESP32 project from now on.
Have you been bitten by PSRAM stacks or heap fragmentation on an ESP32? I'd love to hear how you tracked it down.
I'm Hassan Naeem, an AI engineer who also builds hardware for fun. More of my projects, including live demos, are at hassan-naeem.com.
Top comments (0)