Captive portal example not working #247

perotom · 2025-07-29T09:42:08Z

perotom
Jul 29, 2025

Platform

ESP32

IDE / Tooling

PlatformIO

What happened?

I get the captive portal example not working on Android or iOS. It connected to the device and I can put in the router ip address, but there is no pop-up of the captive portal when connecting to the WiFi. It used to work with the old library (before the Repo changed names). Using esp32-s3-devkit.

Stack Trace

11:41:06.931 > Configuring access point...

Minimal Reproductible Example (MRE)

// SPDX-License-Identifier: LGPL-3.0-or-later
// Copyright 2016-2025 Hristo Gochkov, Mathieu Carbou, Emil Muratov

#include <DNSServer.h>
#include <AsyncTCP.h>
#include <WiFi.h>
#include "ESPAsyncWebServer.h"

static DNSServer dnsServer;
static AsyncWebServer server(80);

class CaptiveRequestHandler : public AsyncWebHandler {
public:
  bool canHandle(__unused AsyncWebServerRequest *request) const override {
    return true;
  }

  void handleRequest(AsyncWebServerRequest *request) {
    AsyncResponseStream *response = request->beginResponseStream("text/html");
    response->print("<!DOCTYPE html><html><head><title>Captive Portal</title></head><body>");
    response->print("<p>This is our captive portal front page.</p>");
    response->printf("<p>You were trying to reach: http://%s%s</p>", request->host().c_str(), request->url().c_str());
    response->printf("<p>Try opening <a href='http://%s'>this link</a> instead</p>", WiFi.softAPIP().toString().c_str());
    response->print("</body></html>");
    request->send(response);
  }
};

void setup() {
  Serial.begin(115200);
  Serial.println();
  Serial.println("Configuring access point...");
  if (!WiFi.softAP("esp-captive")) {
    Serial.println("Soft AP creation failed.");
    while (1);
  }

  dnsServer.start(53, "*", WiFi.softAPIP());
  server.addHandler(new CaptiveRequestHandler()).setFilter(ON_AP_FILTER);  // only when requested from AP
  // more handlers...
  server.begin();
}

void loop() {
  dnsServer.processNextRequest();
}

I confirm that:

I have read the documentation.
I have searched for similar discussions.
I have searched for similar issues.
I have looked at the examples.
I have upgraded to the lasted version of ESPAsyncWebServer (and AsyncTCP for ESP32).

me-no-dev · 2025-07-29T10:36:08Z

me-no-dev
Jul 29, 2025
Maintainer

this has nothing to do with the web server itself. new OS versions have new requirements. Are you using PlatformIO or pioarduino?

6 replies

me-no-dev Jul 29, 2025
Maintainer

I have a proposed solution, but you being on PlatformIO means that your Arduino framework is very old and unsupported, so nothing further we can do. Even if we "fix" the example, it will still not work for you

perotom Jul 29, 2025
Author

Thanks for the information. Strangely it worked with the older version of the library. I will need to figure out which version this was.

me-no-dev Jul 29, 2025
Maintainer

again, this has nothing to do with the web server library itself. It just provides a page. for your phone to forward you to that page (open popup) there are other things at play. DNS and DHCP options. DNS is already set, but your Arduino version does not yet support the DHCP option necessary. Only the latest version does and that does not come through PlatformIO, but through pioarduino (which is compatible with PlatformIO). So you either move to pioarduino or there is nothing that this or older version of this library will do for you

perotom Jul 29, 2025
Author

I just recreated a working example from the old library. With version 2.10.8 and platformio.ini:

[env:esp32-s3-devkitc-1]
platform = espressif32
board = esp32-s3-devkitc-1
framework = arduino

the following code works without problems:

// SPDX-License-Identifier: LGPL-3.0-or-later
// Copyright 2016-2025 Hristo Gochkov, Mathieu Carbou, Emil Muratov

#include <DNSServer.h>
#include <AsyncTCP.h>
#include <WiFi.h>
#include "ESPAsyncWebServer.h"

DNSServer dnsServer;
AsyncWebServer server(80);
IPAddress apIP(8,8,4,4);

class CaptiveRequestHandler : public AsyncWebHandler {
public:
  bool canHandle(AsyncWebServerRequest *request) override {
    return true;
  }

  void handleRequest(AsyncWebServerRequest *request) {
    AsyncResponseStream *response = request->beginResponseStream("text/html");
    response->print("<!DOCTYPE html><html><head><title>Captive Portal</title></head><body>");
    response->print("<p>This is our captive portal front page.</p>");
    response->printf("<p>You were trying to reach: http://%s%s</p>", request->host().c_str(), request->url().c_str());
    response->printf("<p>Try opening <a href='http://%s'>this link</a> instead</p>", WiFi.softAPIP().toString().c_str());
    response->print("</body></html>");
    request->send(response);
  }
};

void setup() {
  Serial.begin(115200);
  Serial.println();
  Serial.println("Configuring access point...");
  WiFi.softAP("esp-captive");
  WiFi.softAPConfig(apIP, apIP, IPAddress(255, 255, 255, 0));
  dnsServer.setErrorReplyCode(DNSReplyCode::NoError);
  dnsServer.start(53, "*", apIP);
  server.addHandler(new CaptiveRequestHandler()).setFilter(ON_AP_FILTER);
  server.begin();
}

void loop() {
  dnsServer.processNextRequest();
}

Same sketch with the new library, doesn't work. I can't tell you why but that's what I can observe and reproduce.

perotom Jul 29, 2025
Author

Actually I just found the issue and it IS related to the Webserver!
Removing .setFilter(ON_AP_FILTER); from the sketch makes it work again. Seems like the macros in

ESPAsyncWebServer/src/WebServer.cpp

Line 26 in 80af245

#if SOC_WIFI_SUPPORTED || CONFIG_ESP_WIFI_REMOTE_ENABLED || LT_ARD_HAS_WIFI

are not working correctly

mathieucarbou · 2025-07-29T10:55:01Z

mathieucarbou
Jul 29, 2025
Maintainer

@perotom : if you want you can try MycilaESPConnect lib which does more or less what the code above does, but with additional routes to support different OS versions. You will be able to see if this is the problem.

Also, are you able to manually reach 192.168.4.1 ?

3 replies

perotom Jul 29, 2025
Author

Thanks for the suggestions but we need a custom captive portal. I will take a look at the detections you did!
Yes I am able to manually reach it. It is just the portal detection doesn't work.

mathieucarbou Jul 29, 2025
Maintainer

Thanks for the suggestions but we need a custom captive portal. I will take a look at the detections you did! Yes I am able to manually reach it. It is just the portal detection doesn't work.

I didn't tell you to use the lib in your project. I told you to try it to see if you have a captive portal issue with it. The base code is common but MycilaESPConnect adds more routes to supporte captive portal triggers for specific OS / brands.

perotom Jul 29, 2025
Author

Yes thank you for the help! I will take a look at it ;)

Captive portal example not working #247

Uh oh!

Uh oh!

perotom Jul 29, 2025

Platform

IDE / Tooling

What happened?

Stack Trace

Minimal Reproductible Example (MRE)

I confirm that:

Replies: 2 comments · 9 replies

Uh oh!

me-no-dev Jul 29, 2025 Maintainer

Uh oh!

me-no-dev Jul 29, 2025 Maintainer

Uh oh!

perotom Jul 29, 2025 Author

Uh oh!

me-no-dev Jul 29, 2025 Maintainer

Uh oh!

Uh oh!

perotom Jul 29, 2025 Author

Uh oh!

perotom Jul 29, 2025 Author

Uh oh!

mathieucarbou Jul 29, 2025 Maintainer

Uh oh!

perotom Jul 29, 2025 Author

Uh oh!

mathieucarbou Jul 29, 2025 Maintainer

Uh oh!

perotom Jul 29, 2025 Author

perotom
Jul 29, 2025

Replies: 2 comments 9 replies

me-no-dev
Jul 29, 2025
Maintainer

me-no-dev Jul 29, 2025
Maintainer

perotom Jul 29, 2025
Author

me-no-dev Jul 29, 2025
Maintainer

perotom Jul 29, 2025
Author

perotom Jul 29, 2025
Author

mathieucarbou
Jul 29, 2025
Maintainer

perotom Jul 29, 2025
Author

mathieucarbou Jul 29, 2025
Maintainer

perotom Jul 29, 2025
Author