FAQ

The purpose of this FAQ / Troubleshooting is to respond to questions commonly asked in Issues section and on ESP8266 Community forum.

Where possible we are going right to the answer and provide it within one or two paragraphs. If it takes more than that, you will see a link to “Read more” details.

Please feel free to contribute if you believe that some frequent issues are not covered below.

I am getting “espcomm_sync failed” error when trying to upload my ESP. How to resolve this issue?

This message indicates issue with uploading ESP module over a serial connection. There are couple of possible causes, that depend on the type of your module, if you use separate USB to serial converter.

Read more.

Why esptool is not listed in “Programmer” menu? How do I upload ESP without it?

Do not worry about “Programmer” menu of Arduino IDE. It doesn’t matter what is selected in it — upload now always defaults to using esptool.

Ref. #138, #653 and #739.

My ESP crashes running some code. How to troubleshoot it?

The code may crash because of s/w bug or issue with your h/w. Before entering an issue report, please perform initial troubleshooting.

Read more.

How can I get some extra KBs in flash ?

• Using *printf() with floats is enabled by default. Some KBs of flash can be saved by using the option --nofloat with the boards generator:

  ./tools/boards.txt.py --nofloat --boardsgen

• Use the debug level option NoAssert-NDEBUG (in the Tools menu)

Read more.

About WPS

From release 2.4.2 and ahead, not using WPS will give an exra ~4.5KB in heap.

In release 2.4.2 only, WPS is disabled by default and the board generator is required to enable it:

./tools/boards.txt.py --allowWPS --boardsgen

Read more.

For platformIO (and maybe other build environments), you will also need to add the build flag: -D NO_EXTRA_4K_HEAP

This manual selection is not needed starting from 2.5.0 (and in git version). WPS is always available, and not using it will give an extra ~4.5KB compared to releases until 2.4.1 included.

This Arduino library doesn’t work on ESP. How do I make it work?

You would like to use this Arduino library with ESP8266 and it does not perform. It is not listed among libraries verified to work with ESP8266.

Read more.

In the IDE, for ESP-12E that has 4M flash, I can choose 4M (1M SPIFFS) or 4M (3M SPIFFS). No matter what I select, the IDE tells me the maximum code space is about 1M. Where does my flash go?

The reason we cannot have more than 1MB of code in flash has to do with a hardware limitation. Flash cache hardware on the ESP8266 only allows mapping 1MB of code into the CPU address space at any given time. You can switch mapping offset, so technically you can have more than 1MB total, but switching such “banks” on the fly is not easy and efficient, so we don’t bother doing that. Besides, no one has so far complained about 1MB of code space being insufficient for practical purposes.

The option to choose 3M or 1M SPIFFS is to optimize the upload time. Uploading 3MB takes a long time so sometimes you can just use 1MB. Other 2MB of flash can still be used with ESP.flashRead and ESP.flashWrite APIs if necessary.

I have observed a case when ESP.restart() doesn’t work. What is the reason for that?

You will see this issue only if serial upload was not followed by a physical reset (e.g. power-on reset). For a device being in that state ESP.restart will not work. Apparently the issue is caused by one of internal registers not being properly updated until physical reset. This issue concerns only serial uploads. OTA uploads are not affected. If you are using ESP.restart, the work around is to reset ESP once after each serial upload.

Ref. #1017, #1107, #1782

How to resolve “Board generic (platform esp8266, package esp8266) is unknown” error?

This error may pop up after switching between staging and stable esp8266 / Arduino package installations, or after upgrading the package version Read more.

How to clear TCP PCBs in time-wait state ?

This is not needed anymore:

PCBs in time-wait state are limited to 5 and removed when that number is exceeded.

Ref. lwIP-v1.4, lwIP-v2

For reference:

Time-wait PCB state helps TCP not confusing two consecutive connections with the same (s-ip,s-port,d-ip,d-port) when the first is already closed but still having duplicate packets lost in internet arriving later during the second. Artificially clearing them is a workaround to help saving precious heap.

The following lines are compatible with both lwIP versions:

// no need for #include
struct tcp_pcb;
extern struct tcp_pcb* tcp_tw_pcbs;
extern "C" void tcp_abort (struct tcp_pcb* pcb);
void tcpCleanup (void) {
  while (tcp_tw_pcbs)
    tcp_abort(tcp_tw_pcbs);
}

Ref. #1923

Why is there a board generator and what about it ?

The board generator is a python script originally intended to ease the Arduino IDE’s boards.txt configuration file about the multitude of available boards, especially when common parameters have to be updated for all of them.

This script is also used to manage uncommon options that are currently not available in the IDE menu.

Read more.