ESP32 IllegalInstruction: the CPU hit something that is not code
The CPU fetched an instruction it does not recognise. ESP-IDF's own guide lists a short set of causes, and one of them catches a lot of C++ code that compiled without a warning.
Guru Meditation Error: Core 0 panic'ed (IllegalInstruction). Exception was unhandled. Memory dump at 0x400d25e0: 0000f01d 00000000 00000000 Backtrace: 0x400d25e3:0x3ffb5e40 0x4008a4a2:0x3ffb5e60
On RISC-V chips it is Illegal instruction.
The usual causes
- A FreeRTOS task function returned. A task must never return; to end it, call
vTaskDelete(NULL)at the end of the function. - A C++ function that should return a value reaches its end without
return. That is undefined behaviour, and with optimisation on the compiler often leaves out the rest of the function, so the CPU runs into whatever follows. ESP-IDF turns this into a build error with-Werror=return-type; if your project or an Arduino setup turned warnings off, it only shows up at run time. Turn the warning back on and fix every function it names. - The next instruction could not be read from SPI flash: the flash pins were reconfigured as GPIO or UART, or something external is connected to them. On most ESP32 modules GPIO 6 to 11 are the flash; do not use them.
- A bad function pointer that happened to point at data rather than at nothing (otherwise it is InstrFetchProhibited).
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: InstrFetchProhibited · Stack overflow · Cache disabled but cached memory region accessed · LoadProhibited. 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