ESP32 "CORRUPT HEAP: Bad head" and "Bad tail"
The heap found its own bookkeeping overwritten. The code that crashes is only the code that noticed; the bug is whatever wrote past a buffer, or into memory after freeing it, some time before.
CORRUPT HEAP: Bad tail at 0x3ffe270a. Expected 0xbaad5678 got 0xbaac5678 assertion "head != NULL" failed: file "…/components/heap/multi_heap_poisoning.c", line 201, function: multi_heap_free abort() was called at PC 0x400dca43 on core 0
Newer ESP-IDF versions print the assertion as assert failed: multi_heap_free multi_heap_poisoning.c:… (head != NULL); the first line is the same.
What it means
ESP-IDF's heap keeps markers next to each allocation and checks them on free and with heap poisoning on. Bad tail: something wrote past the end of a block. Bad head: something wrote before its start, or into a block that was already freed and reused.
The usual causes
- One byte too few:
malloc(strlen(s))without the+ 1for the terminating zero. - Copying more than the buffer holds:
memcpywith the source length instead of the destination size, a received packet longer than expected. - Use after free: a pointer kept after
free, often in another task or a callback. - Freeing twice, or freeing something that was not allocated with
malloc.
Catch the culprit
- In menuconfig, set Heap memory debugging → Heap corruption detection to Comprehensive. Freed memory is then filled with a pattern, so a use after free fails right where it happens.
- Call
heap_caps_check_integrity_all(true)at points in your code; the first call that fails is just after the overwrite.
Espressif's Heap Memory Debugging guide has the details.
Find the line
The Backtrace: line is a list of PC:SP pairs, innermost call first. To turn the addresses into functions and lines you need the ELF of exactly the build that crashed:
- ESP-IDF:
idf.py monitordecodes it as it prints. For a backtrace you copied,xtensa-esp32-elf-addr2line -pfiaC -e build/app.elf 0x400d1d4b 0x400d1e59(riscv32-esp-elf-addr2lineon the C3, C6 and other RISC-V chips). - Arduino: the ELF is in the sketch's build folder (Sketch → Export Compiled Binary, or the path in the verbose build output).
- In the browser: paste the crash and drop the ELF into the free ESP32 exception decoder. Nothing is uploaded.
When it happens in the field
On your desk the crash prints to the serial monitor. On a device in someone else's building it prints to a port nobody is reading, the chip restarts, and all you hear is that it "sometimes hangs". Pinscope keeps the panic reason and backtrace across the restart, sends them on the next connection and decodes them with the ELF of the build that crashed, so you get the function and line without anyone at the device. Free for three devices. How crash reporting from the field works.
Related errors: Stack overflow · StoreProhibited · LoadProhibited · rst:0x… reset reasons. All ESP32 errors: the list. Messages and causes from ESP-IDF's panic handler and Espressif's Fatal Errors guide.
More
- Remote access to an ESP32 without TLS: what it measured and what it costs
- Reaching an ESP32 web server from outside its network
- Updating ESP32 firmware over the internet, with rollback
- Guru Meditation Error: decoding the backtrace, and crashes from the field
- Remote logging: ESP_LOG without a serial cable
- Heap and stack monitoring in the field
- An ESP32 behind CGNAT, 4G or Starlink
- TLS memory usage on the ESP32, and how to reduce it
- Sharing an ESP32 sensor page with anyone, without port forwarding
- ArduinoOTA over the internet, with a rollback
- ESP32 remote access compared: port forwarding, ngrok, Cloudflare Tunnel, Tailscale
- esp_http_server slow? The 250 ms delay and the fix
- Before the first ESP32 ships: a field support checklist
- ESP32 exception decoder: a Guru Meditation backtrace to lines, in the browser