ESP8266 is a low-cost Wi-Fi chip that supports full TCP/IP stack. Till date, numerous types of boards are developed using ESP8266. The developers implement various programming languages to program this chip. You can use very basic level AT commands, low-level C/C++ language, or high-level and users friendly languages like Arduino, Micropython, and NodeMCU. The possibilities are virtually endless. But, ESP8266 sometime shows errors while connected to the serial monitor.

Understanding The Error Messages

The error messages are displayed in predefined codes. Unless you know the code, you can never understand what it says. ESP8266 error messages can be categorized into 3 types – 1) Reset causes, 2) Boot modes, and 3) Fatal Exceptions. Though some can argue that boot mode is not exactly an “error message”, but sometimes it really helps to diagnose a runtime error. Explanation of all the three error messages are below:

1. Reset Causes

Each time ESP8266 reboots, the ROM code will print out a number corresponding to the reset cause. You can verify the cause of the reset based on the number. Use this as a debugging method when you cannot start the user program and need to analyze the cause of the reset. The chart is given below,

Reset Cause No. Description
0 Unidentified
1 Power reboot or normal boot
2 External reset using reset pin or wake up from deep sleep
3 Software reset
4 Hardware watchdog (WDT) reset


rst cause: 2   ->  Normal reset using reset peen or woke up from a deep-sleep.
rst cause: 4   ->  Device encountered a hardware WDT reset.

2. Boot Modes

On reboot, ESP8266 prints the boot mode too. The boot mode message helps to find out two important information: pin mode of three GPIO pins and the location of the boot file used. A boot mode message looks like below,

boot mode :  (5,6)

So, the pattern is – boot mode :  (m,n), where represents the state of three GPIO pins – 15, 0, and 2, and represents the location of the boot file used.

The following table shows the GPIO states as per the value of m,

0 -> ( logic LOW) = 0 Volt            1 -> (Logic HIGH) = 3.3 volt
Value of “m” GPIO15 GPIO0 GPIO2 Mode
0 0 0 0 Invalid
1 0 0 1 UART
2 0 1 0 Invalid
3 0 1 1 Flash
4 1 0 0 SDIO
5 1 0 1 SDIO
6 1 1 0 SDIO
7 1 1 1 SDIO

The table below shows different boot modes for different states of the GPIOs.


FlashMode and BootMode ESP12E

The following table shows the boot modes as per the value of n,

Value of “n” SD_sel != 3 SD_sel == 3
0 Remapping _
1 UART boot _
2 Jump boot _
3 Flash boot _
4 SDIO LowSpeed V2 IO UART1 booting
5 SDIO HighSpeed V1 IO UART1 booting
6 SDIO LowSpeed V1 IO UART1 booting
7 SDIO HighSpeed V2 IO UART1 booting


boot mode :  (3,6)  ->  GPIO 15 is low, GPIO 0 is high, GPIO 2 high, esp8266 booted from flash memory. SDIO LowSpeed v1 IO, UART1 booting.

3. Fatal Exceptions

When a program crashes, it prints out an error message containing a fatal exception number. You can debug the crash based on the Fatal exception number.

The following table shows common Fatal exceptions and their possible causes.

Fatal Exception No. Details Possible Causes
0 Command is invalid 1. Damaged .BIN binaries
2. Wild pointers
6 Division by zero Division by zero
9 unaligned read/write operation addresses 1. Unaligned read/write cache addresses
2. Wild pointers
28/29 Access to invalid addresses 1. Access to cache after it’s turned off
2. Wild pointers

Example: (As per the documentation of The explanation seemed a bit unclear there)

Fatal exception (28): 
epc1=0x4025bfa6, epc2=0x00000000, epc3=0x00000000, excvaddr=0x0000000f, depc=0x00000000

If is used, verify that the exception address is “0x4025bfa6” in the file. If eagle.irom0text.bin is used, verify the cause of the fatal exception in the eagle.S file. If the address of exception cannot be found, it means that the crash occurs during an interrupt, or that there is a code problem in ROM, such as: –

  • 4000e190
  • 4000df48
  • 4000dea8
  • 4000de84
  • 4000e1e0


The above tables and explanations will help you to debug your codes from the error messages. But, there are a few tricks that can be followed to avoid such problems. Making proper wirings is one of them. Even a slightly loose connection can yield tons of errors and is enough to become your nightmare. Even if you are super sure that connections are pretty okay, still check it again. Disconnect all existing wirings and connect them again.

Try to avoid using any breadboard. It seems strange, but there’s a reason. You cannot be sure about the internal connections of the breadboard. Always try to solder wires and external components directly with ESP8266 breakout boards for an error-free result. This simple trick solved many of my problems dramatically.

Another important and clever trick is using a pull-up or a pull-down resistor instead of directly connecting boot selector GPIOs to Vcc or ground. Also, don’t forget to connect a pull-up resistor between reset pin and Vcc. A 10K ohm resistor will work just fine as a pull-up/down resistor.

6 thoughts on “ESP8266 Error Messages And Exceptions Explained

  1. Thanks a lot for the info. I checked out the exception code meanings in the xtensa’s architecture manual but it was nice to confirm here what I gleaned there.


  2. Thanks for the article. I had one day struggling with Fatal 9 wild pointer. Here reporting getFreeHeap() periodically helped me to spot the bug – memory leak. A good practice is to detect heap crash and make a reset before for proper restart. Even better is to find that the free heap stays high enough during long test run.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s