Skip to content


After connected, AutoConnect menu performs but no happens.

If you can access the AutoConnect root path as http://ESP8266IPADDRESS/_ac from browser, probably the Sketch uses ESP8266WebServer::handleClient() without AutoConnect::handleRequest().
For AutoConnect menus to work properly, call AutoConnect::handleRequest() after ESP8266WebServer::handleClient() invoked, or use AutoConnect::handleClient(). AutoConnect::handleClient() is equivalent ESP8266WebServer::handleClient combined AutoConnect::handleRequest().

See also the explanation here.

After updating to AutoConnect v1.0.0, established APs disappear from Open SSIDs with ESP32.

Since AutoConnect v1.0.0 for ESP32, the storage location in the flash of established credentials has moved from EEPROM to Preferences. After You update AutoConnect to v1.0.0, past credentials saved by v0.9.12 earlier will not be accessible from the AutoConnect menu - Open SSIDs. You need to transfer once the stored credentials from the EEPROM area to the Preferences area.

You can migrate the past saved credentials using CreditMigrate.ino which the examples folder contains.

Needs to Arduino core for ESP32 1.0.2 or earlier

EEPROM area with arduino-esp32 core 1.0.3 has moved from partition to the nvs. CreditMigrate.ino requires arduino-esp32 core 1.0.2 or earlier to migrate saved credentials.

An esp8266ap as SoftAP was connected but Captive portal does not start.

Captive portal detection could not be trapped. It is necessary to disconnect and reset ESP8266 to clear memorized connection data in ESP8266. Also, It may be displayed on the smartphone if the connection information of esp8266ap is wrong. In that case, delete the connection information of esp8266ap memorized by the smartphone once.

Cannot automatically reconnect to a WiFi Hotspot

WiFi Hotspot ability using a cell phone has no official designation name, but it is commonly referred to as a mobile hotspot or a Personal Hotspot. Generally, this feature using data communication with your cellular to ensure the connection to the Internet. AutoConnect allows you to connect to a WiFi hotspot that has been temporarily launched as an access point and then stores a credential for establishing a connection in the same way as a regular fixed access point.

However, there's a case where it may not be able to reconnect automatically to a known WiFi hotspot. For security reasons, some device operating systems randomly change the MAC address of the WiFi hotspot at each boot for a hotspot. (Especially iOS14) AutoConnect uses the BSSID to find the known SSID from among WiFi signals being broadcast. (it's the MAC address) This method works if the BSSID that the hotspot originates is fixed, but AutoConnect will not be able to find known SSIDs when it changes.
Consider activating the AUTOCONNECT_APKEY_SSID definition if you want to reconnect automatically to a known WiFi hotspot.

Cannot immobilize the MAC address of Personal Hotspot

We may not be able to immobilize the MAC address of Personal Hotspot on iOS14. This specification change seems to be related to the private network connection enhancement of iOS14 devices. I found this change during the testing phase, but it is not the confirmed information. (iOS14 offers an option to immobilize the MAC address as a client device, but there is still no option to immobilize it where the device became a hotspot)

Captive portal does not pop up.

If your ESP module is already transparent to the internet, the captive portal screen will not pop up even if AutoConnectConfig::retainPortal is enabled. Some people have mistaken sometimes about the behavioral condition of the Captive portal, it only pops up automatically when the ESP module is disconnected state from the Internet.

We will hypothesize that you keep the ESP module with AP_STA mode by specifing the retainPortal and already connect to one of the access points which has Internet transparency as a WiFi client. At this time, your ESP module can already quote the DNS globally. Even if you take out the cellphone and access the esp32ap, the OS of your cellphone will determine that the access point (i.e. esp32ap) is transparent to the Internet. That is, the captive portal does not pop up.

Compile error that 'EEPROM' was not declared in this scope

If the user sketch includes the header file as EEPROM.h, this compilation error may occur depending on the order of the #include directives. AutoConnectCredentials.h including in succession linked from AutoConnect.h defines NO_GLOBAL_EEPROM internally, so if your sketch includes EEPROM.h after AutoConnect.h, the EEPROM global variable will be lost.

If you use EEPROM with your sketch, declare #include <EEPROM.h> in front of #include <AutoConnect.h>.

Compile error that 'ESPhttpUpdate' was not declared in this scope

If the user sketch includes the header file as ESP8266httpUpdate.h, this compilation error may occur depending on the order of the #include directives. AutoConnectUpdate.h including in succession linked from AutoConnect.h defines NO_GLOBAL_HTTPUPDATE internally, so if your sketch includes ESP8266httpUpdate.h after AutoConnect.h, the ESPhttpUpdate global variable will be lost.

You can avoid a compile error in one of two ways:

  1. Disable an AutoConnectUpdate feature if you don't need.

    You can disable the AutoConnectUpdate feature by commenting out the AUTOCONNECT_USE_UPDATE macro in the AutoConnectDefs.h header file.


  2. Change the order of #include directives.

    With the Sketch, #include <ESP8266httpUpdate.h> before #include <AutoConnect.h>.

Connection lost immediately after establishment with AP

A captive portal is disconnected immediately after the connection establishes with the new AP. This is a known problem of ESP32, and it may occur when the following conditions are satisfied at the same time.

  • SoftAP channel on ESP32 and the connecting AP channel you specified are different. (The default channel of SoftAP is 1.)
  • NVS had erased by erase_flash causes the connection data lost. The NVS partition has been moved. Never connected to the AP in the past.
  • There are receivable multiple WiFi signals which are the same SSID with different channels using the WiFi repeater etc. (This condition is loose, it may occur even if there is no WiFi repeater.)
  • Or the using channel of the AP which established a connection is congested with the radio signal on the same band. (If the channel crowd, connections to known APs may also fail.)

Other possibilities

The above conditions are not absolute. It results from my investigation, and other conditions may exist.

To avoid this problem, try changing the channel.

ESP32 hardware equips only one RF circuitry for WiFi signal. At the AP_STA mode, ESP32 as an AP attempts connect to another AP on another channel while keeping the connection with the station then the channel switching will occur causes the station may be disconnected. But it may not be just a matter of channel switching causes ESP8266 has the same constraints too. It may be a problem with AutoConnect or the arduino core or SDK issue. This problem will persist until a specific solution.

Data saved to EEPROM is different from my sketch wrote.

By default, AutoConnect saves the credentials of the established connection into EEPROM. The credential area of EEPROM used by AutoConnect will conflict with data owned by the user sketch if without measures taken. It will destroy the user sketch data and the data stored in EEPROM by AutoConnect with each other.
You have the following two options to avoid this conflict:

  • Move the credential saving area of EEPROM.
    You can protect your data from corruption by notifying AutoConnect where to save credentials. Notification of the save location for the credentials uses AutoConnectConfig::boundaryOffset option. Refer to the chapter on Advanced usage for details.

  • Suppresses the automatic save operation of credentials by AutoConnect.
    You can completely stop saving the credentials by AutoConnect. However, if you select this option, you lose the past credentials which were able to connect to the AP. Therefore, the effect of the automatic reconnection feature will be lost.
    If you want to stop the automatic saving of the credentials, uses AutoConnectConfig::autoSave option specifying AC_SAVECREDENTIAL_NEVER. Refer to the chapter on Advanced usage for details.

Does not appear esp8266ap in smartphone.

Maybe it is successfully connected at the 1st-WiFi.begin. ESP8266 remembers the last SSID successfully connected and will use at the next. It means SoftAP will only start up when the first WiFi.begin() fails.

The saved SSID would be cleared by WiFi.disconnect() with WIFI_STA mode. If you do not want automatic reconnection, you can erase the memorized SSID with the following simple sketch.

#include <ESP8266WiFi.h>

void setup() {
  if (WiFi.waitForConnectResult() == WL_CONNECTED) {
    while (WiFi.status() == WL_CONNECTED)
  Serial.println("WiFi disconnected.");

void loop() {
You can interactively check the WiFi state of ESP8266.

Please try ESPShaker. It is ESP8266 interactive serial command processor.

Does not response from /_ac.

Probably WiFi.begin failed with the specified SSID. Activating the debug printing will help you to track down the cause.

Hang up after Reset?

If ESP8266 hang up after reset by AutoConnect menu, perhaps manual reset is not yet. Especially if it is not manual reset yet after uploading the Sketch, the boot mode will stay 'Uart Download'. There is some discussion about this on the Github's ESP8266 core: 1

If you received the following message, the boot mode is still sketch uploaded. It needs to the manual reset once.

ets Jan  8 2013,rst cause:2, boot mode:(1,6) or (1,7)
ets Jan  8 2013,rst cause:4, boot mode:(1,6) or (1,7)
wdt reset

The correct boot mode for starting the Sketch is (3, x).

ESP8266 Boot Messages

It is described by ESP8266 Non-OS SDK API Reference, section A.5.

Messages Description
rst cause 1: power on
2: external reset
4: hardware watchdog reset
boot mode
(the first parameter)
1: ESP8266 is in UART-down mode (and downloads firmware into flash).
3: ESP8266 is in Flash-boot mode (and boots up from flash).

How can I detect the captive portal starting?

You can use the AutoConnect::onDetect exit routine. For more details and an implementation example of the onDetect exit routine, refer to the chapter "Captive portal start detection".

How change HTTP port?

HTTP port number is defined as a macro in AutoConnectDefs.h header file. You can change it directly with several editors and must re-compile.


How change SSID or Password in Captive portal?

You can change both by using AutoConnectConfig::apid and AutoConnectConfig::psk. Refer to section Change SSID and Password for SoftAP in Advanced usage.

How do I detach the ArdunoJson?

If you don't use ArduinoJson at all, you can detach it from the library. By detaching ArduinoJson, the binary size after compilation can be reduced. You can implement custom Web pages with your sketches without using ArduinoJson. Its method is described in Custom Web pages w/o JSON.
To completely remove ArduinoJson at compile-time from the binary, you need to define a special #define directive for it. And if you define the directive, you will not be able to use the OTA update with the update server feature as well as AutoConnectAux described by JSON.

To exclude ArduinoJson at compile-time, give the following #define directive as a compiler option such as the arduino-cli or PlatformIO.


For example, add the following description to the [env] section of the platformio.ini file with the build-flags.


How place HTML elements undefined in AutoConnectElements?

AutoConnectElement can be applied in many cases when trying to place HTML elements that are undefined in AutoConnectElemets on custom Web pages. See Handling the custom Web Pages section.

How erase the credentials saved in EEPROM?

Make some sketches for erasing the EEPROM area, or some erasing utility is needed. You can prepare the Sketch to erase the saved credential with AutoConnectCredential. The AutoConnectCrendential class provides the access method to the saved credential in EEPROM and library source file is including it. Refer to 'Saved credential access' on section Appendix for details.


With the ESPShaker, you can access EEPROM interactively from the serial monitor, and of course you can erase saved credentials.

Link button to AutoConnect menu can be embedded into Sketch's web page. The root path of the menu is /_ac by default and embed the following <a></a> tag in the generating HTML.

<a style="background-color:SteelBlue; display:inline-block; padding:7px 13px; text-decoration:none;" href="/_ac">MENU</a>

How much memory does AutoConnect consume?

Sketch size

  1. For ESP8266
    It increases about 53K bytes compared to the case without AutoConnect. A sketch size of the most simple example introduced in the Getting started is about 330K bytes. (270K byte without AutoConnect)

  2. For ESP32
    The BIN size of the sketch grows to over 1M bytes. In the case of a sketch with many custom Web pages, when applying the partition table for the default scheme, the remaining flash size that can be utilized by the user application may be less than 200K bytes. Therefore, it is advisable to resize the partition to make more available space for the application. The ESP32 arduino core has various partition schemes, and you can choose it according to your Sketch feature.
    You can change the partition scheme from the Tools > Partition Scheme menu of Arduino IDE.

Change the partition scheme with PlatformIO

Use board_build.partitions directive with platformio.ini.

board_build.partitions = min_spiffs.csv
Details for the PlatformIO documentation.

Heap size

It consumes about 2K bytes in the static and about 12K bytes are consumed at the moment when menu executed.

I cannot complete to Wi-Fi login from smartphone.

Because AutoConnect does not send a login success response to the captive portal requests from the smartphone. The login success response varies iOS, Android and Windows. By analyzing the request URL of different login success inquiries for each OS, the correct behavior can be implemented, but not yet. Please resets ESP8266 from the AutoConnect menu.

I cannot see the custom Web page.

If the Sketch is correct, a JSON syntax error may have occurred. In this case, activate the AC_DEBUG and rerun. If you take the message of JSON syntax error, the Json Assistant helps syntax checking. This online tool is provided by the author of ArduinoJson and is most consistent for the AutoConnect.

Saved credentials are wrong or lost.

A structure of AutoConnect saved credentials has changed two times throughout enhancement with v1.0.3 and v1.1.0. In particular, due to enhancements in v1.1.0, AutoConnectCredential data structure has lost the backward compatibility with previous versions. You must erase the flash of the ESP module using the esptool completely to save the credentials correctly with v1.1.0.

esptool -c esp8266 (or esp32) -p [COM_PORT] erase_flash

Some AutoConnect page is cut off.

It may be two possibilities as follows:

  1. Packet loss during transmission due to a too weak WiFi signal.
  2. Heap is insufficient memory. AutoConnect entrusts HTML generation to PageBuilder that makes heavy use the String::concatenate function and causes memory fragmentation. This is a structural problem with PageBuilder, but it is difficult to solve immediately.

If this issue produces with your sketch, Reloading the page may recover.
Also, you can check the memory running out status by rebuilding the Sketch with PageBuilder's debug log option turned on.

If the heap memory is insufficient, the following message is displayed on the serial console.

[PB] Failed building, free heap:<Size of free heap>

Submit element in a custom Web page does not react.

Is there the AutoConnectElements element named SUBMIT in the custom Web page? (case sensitive ignored) AutoConnect does not rely on the input type=submit element for the form submission and uses HTML form element submit function instead. So, the submit function will fail if there is an element named 'submit' in the form. You can not use SUBMIT as the element name of AutoConnectElements in a custom Web page that declares the AutoConnectSubmit element.

Unable to change any macro definitions by the Sketch.

The various macro definitions that determine the configuration of AutoConnect cannot be redefined by hard-coding with Sketch. The compilation unit has a different AutoConnect library itself than the Sketch, and the configuration definitions in AutoConnectDefs.h are quoted in the compilation for AutoConnect only. For example, the following Sketch does not enable AC_DEBUG and does not change HTTP port also the menu background color:

#define AC_DEBUG                                    // No effect
#define AUTOCONNECT_HTTPPORT    8080                // No effect
#define AUTOCONNECT_MENUCOLOR_BACKGROUND  "#696969" // No effect
#include <ESP8266WiFi.h>
#include <ESP8266WebServer.h>
#include <AutoConnect.h>

AutoConnect Portal;

void setup() {

void loop() {

To enable them, edit AutoConnectDefs.h as the library source code directly, or supply them as the external parameters using a build system like PlatformIO with platformio.ini:

platform = espressif8266
board = nodemcuv2
board_build.f_cpu = 160000000L
board_build.f_flash = 80000000L
board_build.flash_mode = dio
board_build.filesystem = littlefs
build_flags =

Unauthorize error without prompting the login dialog.

The custom web pages that require authentication will occur unauthorized error always without prompting the login dialog under the captive portal state on some OS. This is a captive portal restriction and expected behavior. The captive portal web browser is almost a complete web browser, but while the captive portal session restricts the response to WWW-authenticate requests. (In intrinsically, the captive portal is a mechanism for authentication in itself)

Once you exit from the captive portal session and connect SoftAP IP directly afresh, you can access custom web pages along with prompting a login dialog.

Still, not stable with my sketch.

If AutoConnect behavior is not stable with your sketch, you can try the following measures.

1. Change WiFi channel

Both ESP8266 and ESP32 can only work on one channel at any given moment. This will cause your station to lose connectivity on the channel hosting the captive portal. If the channel of the AP which you want to connect is different from the SoftAP channel, the operation of the captive portal will not respond with the screen of the AutoConnect connection attempt remains displayed. In such a case, please try to configure the channel with AutoConnectConfig to match the access point.

AutoConnect portal;
AutoConnectConfig config; = 3;     // Specifies a channel number that matches the AP
portal.config(config);  // Apply channel configuration
portal.begin();         // Start the portal

Channel selection guide

Espressif Systems has released a channel selection guide.

2. Change the arduino core version

I recommend change installed an arduino core version to the upstream when your sketch is not stable with AutoConnect on each board.

with ESP8266 arduino core

You can select the lwIP variant to contribute for the stable behavior. The lwIP v2 Lower memory option of Arduino IDE for core version 2.4.2 is based on the lwIP-v2. On the other hand, the core version 2.5.0 upstream is based on the lwIP-2.1.2 stable release.

You can select the option from Arduino IDE as Tool menu, if you are using ESP8266 core 2.5.0. It can be select lwIP v2 Lower Memory option. (not lwIP v2 Lower Memory (no features)) It is expected to improve response performance and stability.

with ESP32 arduino core

The arduino-esp32 is still under development. It is necessary to judge whether the problem cause of the core or AutoConnect. Trace the log with the esp32 core and the AutoConnect debug option enabled for problem diagnosis and please you check the issue of arduino-esp32. The problem that your sketch possesses may already have been solved.

3. Turn on the debug log options

To fully enable for the AutoConnect debug logging options, change the following two files.


#define AC_DEBUG

PageBuilder.h 2

#define PB_DEBUG

How to enable the AC_DEBUG, PB_DEBUG

See Debug Print section, and one similarly too.

4. Reports the issue to AutoConnect Github repository

If you can not solve AutoConnect problems please report to Issues. And please make your question comprehensively, not a statement. Include all relevant information to start the problem diagnostics as follows:3

  • Hardware module
  • Arduino core version Including the upstream commit ID if necessary
  • Operating System which you use
  • Your smartphone OS and version (Especially for Android)
  • Your AP information (IP, channel) if related
  • lwIP variant
  • Problem description
  • If you have a STACK DUMP decoded result with formatted by the code block tag
  • the Sketch code with formatted by the code block tag (Reduce to the reproducible minimum code for the problem)
  • Debug messages output (Including arduino core)

I will make efforts to solve as quickly as possible. But I would like you to know that it is not always possible.

Thank you.

  1. This issue has been resolved in ESP8266 core 2.5.0 and later. 

  2. PageBuilder.h exists in the libraries/PageBuilder/src directory under your sketch folder. 

  3. Without this information, the reproducibility of the problem is reduced, making diagnosis and analysis difficult.