ESP8266 Debugging Exceptions

ESP8266 the core includes a Debugging feature that is controllable over the IDE menu. The new menu points manage the real-time Debug messages. It is very useful to sort out watchdog trigger and exception errors. For debugging you can use Serial or Serial 1 and also you can choose the debug level such as WIFI, Core, OTA etc.

Many times you stuck at WDT reset and Stack Exception errors, this is most rarely used tool, many people don’t know it exists. Let’s get know to it, Its very powerful tool comes with NodeMCU or ESP8266.

NodeMCU Exception Debugging

Why I Need Debugging ?

To solve the mysterious problems, and get to know what’s going inside WiFi Library?

How to turn on debugging?

To turn on debugging over same programming serial. Go to tools menu choose debug port Serial

NodeMCU Debug Enable Menu

After Enabling Debug Port Set Debug Level I am using here WIFI

Depending on different program situations you can choose debug levels.

Note 1: Just enabling Debug port and setting Debug level won’t wok, You need to upload you code after enabling these settings.

Note 2: Debug port work’s at 115200 BAUD if you have not set the serial.

To demonstrate it’s uses and I am uploading a blank sketch with serial initialized that is minimum requirement.


For usage of the debugging a Serial connection is required (Serial or Serial1).

The Serial Interface need to be initialized in the setup().

Set the Serial baud rate as high as possible for your Hardware setup.

Minimum sketch to use debugging:

void setup() 

void loop() 

Now lets move how to turn on debugging. After setting and uploading above ketch I am opening serial monitor.

I have not given any SSID, PASSWORD or not written any single line which makes connection with my wifi, but it still connecting. This is called debugging. Many things are going inside ESP8266. That cause Watch Dog Reset issues or other exceptions.

Let’s make exception and see what happens?

void setup() 
void loop() 
   while(1);  //Wait forever 

We got the WDT Soft Trigger >>Stack>> Error

By looking at error and this list of causes you can get clear idea that your code is stuck.

Reset cause Values

  • rst cause : 1
    Power-on-reset, indicates that the ESP8266 went through a power cycle and rebooted as a result of that.
    Often seen randomly if your power supply is dodgy.
  • rst cause : 2
    Fatal Exception, Error in code.
  • rst cause : 4
    Hardware watchdog reset, triggered when your code is stuck or malfunctioning. This is usually a result of improper loading of watchdog timer, which is enabled by default on the SDKs provided by Espressif.
  • rst cause: 5
  • rst cause: 6
    External reset is triggered by the reset pin of the ESP8266. This is the reason you would see when the ESP8266 is reset explicitly via the pin or when the ESP8266 wakes up from deep sleep (because that involves a GPIO driving the reset pin).

Common Fatal Exceptions and Causes

When a program crashes, 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. Description Possible Causes
0 Invalid command 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 address 1.Access to Cache after it is turned off
2.Wild pointers
For example:
Fatal exception (28):
epc1=0x4025bfa6, epc2=0x00000000, epc3=0x00000000, excvaddr=0x0000000f,
• If is used, verify the exception address “0x4025bfa6” in the file. Add print to the user’s code to debug the Fatal exception.
• 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 <memset>
– 4000df48 <memcpy>
– 4000dea8 <memcmp>
– 4000de84 <bzero>
– 4000e1e0 <strstr>
This is how we can sort out these errors.

Debug Level

You can choose debug level as shown at beginning using menu or you can define it in your code.

All defines for the different levels starts with DEBUG_ESP_

a full list can be found here in the boards.txt

Example for own debug messages

The debug messages will be only shown when the Debug Port in the IDE menu is set.

#define DEBUG_MSG(...) DEBUG_ESP_PORT.printf( __VA_ARGS__ )
#define DEBUG_MSG(...)

void setup() {


void loop() {
    DEBUG_MSG("loop %d\n", millis());
This way you can debug all issues related to wifi, ssl, core and many more.
For more common Issues that I found are Listed here with reasons and sample codes that generate exception, without any logical errors or code errors.

Leave a Reply