ESP32 SPIRAM: UART + Network causes heap corruption/crash (affects official firmware v1.27.0) (IDFGH-16944)

[sheng8888888888]

Answers checklist.

• I have read the documentation ESP-IDF Programming Guide and the issue is not addressed there.
• I have updated my IDF branch (master or release) to the latest version and checked that the issue is present there.
• I have searched the issue tracker for a similar issue and not found a similar issue.

IDF version.

v5.4.2

Espressif SoC revision.

ESP32-D0WDR2-V3 (revision v3.1)

Operating System used.

macOS

How did you build your project?

Command line with Make

If you are using Windows, please specify command line type.

CMD

Development Kit.

ESP32-D0WDR2-V3 (revision v3.1)

Power Supply used.

USB

What is the expected behavior?

UART should work correctly with SPIRAM enabled, regardless of whether Network (WiFi/Ethernet) is initialized before or after UART.

The following code should not crash:

import gc, network
from machine import UART

Initialize Network first

wlan = network.WLAN(network.STA_IF)
wlan.active(True)

Then initialize UART

u = UART(1, 115200)
u.init(tx=32, rx=33, rxbuf=1024)

This should work

gc.collect()
print(gc.mem_free()) # Should print available memory, not crash

What is the actual behavior?

When Network (WiFi or Ethernet) is activated before UART initialization on ESP32 with SPIRAM, calling gc.mem_free() or gc.collect() after UART.init() causes a crash.

Crash types observed:

• v1.27.0 (ESP-IDF 5.5.1): "Interrupt wdt timeout on CPU1"
• v1.26.x (ESP-IDF 5.4.2): "CORRUPT HEAP" at SPIRAM address 0x3f800xxx, then "LoadProhibited"

Key findings:

• Only UART (no Network): ✅ Works
• Only Network (no UART): ✅ Works
• UART first, then Network: ✅ Works
• Network first, then UART: ❌ Crash

The crash is 100% reproducible with the minimal test case.

Steps to reproduce.

1. Flash official ESP32 SPIRAM firmware (ESP32_GENERIC-SPIRAM-20251209-v1.27.0.bin) to an ESP32-WROVER or any ESP32 with SPIRAM

2. Connect via serial REPL

3. Run the following code:

import gc, network
from machine import UART

# Step 1: Activate WiFi
wlan = network.WLAN(network.STA_IF)
wlan.active(True)
gc.collect()
print("After Network:", gc.mem_free())  # Works fine

# Step 2: Create and init UART
u = UART(1, 115200)
u.init(tx=32, rx=33, rxbuf=1024)

# Step 3: This crashes
gc.collect()
print("After UART:", gc.mem_free())  # CRASH HERE

Debug Logs.

Connected to MicroPython at /dev/tty.usbmodem59570526701
Use Ctrl-] or Ctrl-x to exit this shell
ets Jul 29 2019 12:21:46

rst:0x1 (POWERON_RESET),boot:0x16 (SPI_FAST_FLASH_BOOT)
configsip: 153911750, SPIWP:0xee
clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
mode:DIO, clock div:2
load:0x3fff0030,len:4200
load:0x40078000,len:15236
load:0x40080400,len:3332
entry 0x400805a8
MicroPython v1.27.0 on 2025-12-09; Generic ESP32 module with SPIRAM with ESP32
Type "help()" for more information.
>>> # Step 1: Activate WiFi (or Ethernet)
>>> import gc, network
>>> wlan = network.WLAN(network.STA_IF)
>>> wlan.active(True)
True
>>> gc.collect()
>>> print("After Network:", gc.mem_free())  # Works fine
After Network: 2085856
>>>
>>> # Step 2: Create UART
>>> from machine import UART
>>> u = UART(1, 115200)
>>> u.init(tx=32, rx=33, rxbuf=1024)
>>>
>>> # Step 3: Check heap - CRASHES
>>> gc.collect()
>>>
>>> print("After UART:", gc.mem_free())

A fatal error occurred. The crash dump printed below may be used to help
determine what caused it. If you are not already running the most recent
version of MicroPython, consider upgrading. New versions often fix bugs.

To learn more about how to debug and/or report this crash visit the wiki
page at: https://github.com/micropython/micropython/wiki/ESP32-debugging

MPY version : v1.27.0 on 2025-12-09
IDF version : v5.5.1
Machine     : Generic ESP32 module with SPIRAM with ESP32

Guru Meditation Error: Core  1 panic'ed (Interrupt wdt timeout on CPU1).

Core  1 register dump:
PC      : 0x401f1648  PS      : 0x00060335  A0      : 0x801f16c0  A1      : 0x3ffd6df0
A2      : 0x00000001  A3      : 0xfffffffc  A4      : 0x00000000  A5      : 0x3ffd6e50
A6      : 0x00000001  A7      : 0x0000abab  A8      : 0x001dc1a9  A9      : 0x00060320
A10     : 0x00000004  A11     : 0x00000000  A12     : 0xb33fffff  A13     : 0x3f424910
A14     : 0x00000001  A15     : 0x3f4248c4  SAR     : 0x00000006  EXCCAUSE: 0x00000006
EXCVADDR: 0x00000000  LBEG    : 0x40092b62  LEND    : 0x40092b6d  LCOUNT  : 0x00000000


Backtrace: 0x401f1645:0x3ffd6df0 0x401f16bd:0x3ffd6e10 0x401f15f4:0x3ffd6e30 0x400d85ca:0x3ffd6e50 0x400d8615:0x3ffd6e90 0x40117991:0x3ffd6ed0 0x400f7f3a:0x3ffd6ef0 0x40123705:0x3ffd6f10 0x400fb56e:0x3ffd6f50 0x40101aad:0x3ffd6f70 0x40101b77:0x3ffd6f90 0x4008606a:0x3ffd6fb0 0x400fb6b4:0x3ffd7060 0x40101aad:0x3ffd70c0 0x40101ac6:0x3ffd70e0 0x401114f2:0x3ffd7100 0x401117ed:0x3ffd7190 0x400f4ad0:0x3ffd71d0


Core  0 register dump:
PC      : 0x40093996  PS      : 0x00060b35  A0      : 0x801ee86d  A1      : 0x3ffbc220
A2      : 0x00000003  A3      : 0x00060b23  A4      : 0x00060b20  A5      : 0x00000000
A6      : 0x3ffb7924  A7      : 0x3ffb790c  A8      : 0x80087046  A9      : 0x3ffbc200
A10     : 0x3ffb7924  A11     : 0x00000001  A12     : 0x00000000  A13     : 0x00000000
A14     : 0x00000000  A15     : 0x00000003  SAR     : 0x0000001d  EXCCAUSE: 0x00000006
EXCVADDR: 0x00000000  LBEG    : 0x00000000  LEND    : 0x00000000  LCOUNT  : 0x00000000


Backtrace: 0x40093993:0x3ffbc220 0x401ee86a:0x3ffbc240 0x401eed07:0x3ffbc260 0x401f03eb:0x3ffbc280




ELF file SHA256: 63f2a8d00

Rebooting...
ets Jul 29 2019 12:21:46

Diagnostic report archive.

N/A - Using official prebuilt MicroPython firmware from micropython.org (ESP32_GENERIC-SPIRAM-20251209-v1.27.0.bin), not building from ESP-IDF source directly.

Bug is reproducible with:

• Official MicroPython v1.27.0 (ESP-IDF 5.5.1)
• Custom MicroPython v1.26.1 build (ESP-IDF 5.4.2)

More Information.

On ESP32 with SPIRAM enabled, initializing a UART after WiFi/Ethernet activation causes heap corruption or watchdog timeout crash.

This bug is confirmed on the official prebuilt firmware ESP32_GENERIC-SPIRAM-20251209-v1.27.0.bin from micropython.org.

The issue occurs with both CONFIG_SPIRAM_USE_MALLOC=y and CONFIG_SPIRAM_USE_CAPS_ALLOC=y configurations.

Environment

Tested and confirmed on:

MicroPython	ESP-IDF	Firmware	Result
v1.27.0	v5.5.1	Official ESP32_GENERIC-SPIRAM	❌ Crash
v1.26.1	v5.4.2	Custom build	❌ Crash
v1.26.0	v5.4.2	Custom build	❌ Crash

[songruo]

I saw you have posted same question at micropython/micropython#18544. Let's wait and see the response from there first :)

[sheng8888888888]

Root Cause Identified - Closing as User Error / Documentation Issue

After further investigation, I found the root cause. This is not a bug but rather an issue with UART1's default pin assignment on SPIRAM-enabled modules.

Root Cause

On ESP32-D0WDR2-V3 (and similar chips with embedded PSRAM), GPIO9/10 are used by the Quad SPI bus for PSRAM data lines (SD2/SD3):

GPIO	Function	Usage
GPIO9	SPIHD (SD2)	PSRAM Quad SPI Data Line 2
GPIO10	SPIWP (SD3)	PSRAM Quad SPI Data Line 3

MicroPython's UART1 defaults to tx=10, rx=9. When calling UART(1, 115200) without explicit pin assignment, the UART driver attempts to reconfigure GPIO9/10, which conflicts with the active PSRAM SPI bus.

Why it crashes

# ❌ Crashes - uses default GPIO9/10, conflicts with PSRAM Quad SPI
u = UART(1, 115200)
u.init(tx=32, rx=33, rxbuf=1024)  # Too late, GPIO9/10 already touched

# ✅ Works - GPIO9/10 never touched
u = UART(1, 115200, tx=32, rx=33, rxbuf=1024)

Why it works after hard reset but fails after soft reset

• After hard reset: PSRAM cache not fully active yet, SPI bus may be idle
• After soft reset: WiFi/Network keeps PSRAM cache active, GPIO9/10 actively used by SPI

Correct Usage

On ESP32 modules with SPIRAM, always specify safe pins in the constructor:

# Correct way for SPIRAM modules
uart = UART(1, 115200, tx=32, rx=33, rxbuf=1024)

Suggestion for MicroPython

Consider one of these improvements:

1. Change default pins for UART1 when CONFIG_SPIRAM=y to avoid GPIO9/10
2. Raise an error if UART1 is instantiated without explicit pins on SPIRAM builds
3. Add documentation warning about GPIO9/10 conflict on SPIRAM modules

Example fix in machine_uart.c:

#if CONFIG_SPIRAM
case UART_NUM_1:
    // GPIO9/10 occupied by PSRAM Quad SPI, require explicit pin assignment
    self->rx = UART_PIN_NO_CHANGE;
    self->tx = UART_PIN_NO_CHANGE;
    break;
#endif

Thanks to the community member who helped narrow this down by testing UART(1, 115200, tx=32, rx=33, rxbuf=1024) vs the two-step initialization.

Closing this as the behavior is expected given the hardware constraints. A separate feature request could be opened for improved defaults/error handling on SPIRAM builds.