ESP32 Captive Portal Not Redirecting or Working

ESP32 Captive Portal Not Redirecting or Working #

If your ESP32 is running a captive portal (such as via WiFiManager or a custom AP+DNS setup), but devices fail to redirect or the portal doesn't show up automatically, you're likely facing a common issue with DNS interception or platform compatibility.

Captive portals rely on several assumptions about browser behavior, network requests, and client OS - and small misconfigurations can prevent the portal from appearing or working as expected.

What Is a Captive Portal? #

A captive portal is a temporary Wi-Fi access point that:

• Presents a configuration webpage automatically when clients connect
• Uses DNS hijacking to redirect all domain requests to a local web page
• Runs in ESP32’s Access Point (AP) mode, usually at IP 192.168.4.1

This is useful for provisioning credentials or device settings when no known Wi-Fi network is available.

Typical Symptoms and What They Mean #

📶 ESP32 Access Point Connects But No Portal Appears #

Your phone or laptop joins the ESP32’s AP, but no popup or redirect occurs. Typing esp32.local fails, and only 192.168.4.1 works.

This suggests the DNS redirection isn’t functioning or the OS is bypassing captive portal detection.

📱 Works on Android, Not macOS #

Operating systems use different heuristics to detect captive portals. For example:

• Android sends a request to connectivitycheck.gstatic.com
• iOS uses captive.apple.com
• Windows probes www.msftconnecttest.com

If these are cached or use HTTPS (which cannot be hijacked), the system won’t trigger a portal popup.

🧯 Portal Fails After Reboot or Sleep #

If you use deep sleep or restart the board without reinitializing the DNS server and web server, the portal becomes unreachable until manually reset.

Causes of Captive Portal Issues #

🌐 DNS Intercept Server Missing or Not Started #

If the DNS server isn’t started, domain lookups won’t be redirected to 192.168.4.1. This breaks automatic portal triggering.

Ensure:

dnsServer.start(53, "*", WiFi.softAPIP());

is called after WiFi.softAP().

Also make sure:

server.begin();

is called for the web server.

⚙️ Browser Uses HTTPS or Encrypted DNS #

Captive portals cannot intercept encrypted traffic (HTTPS or DoH). If the device’s browser goes to https://example.com, the ESP32 can't respond - the handshake fails silently.

Encourage users to visit:

http://192.168.4.1

manually to bypass HTTPS pitfalls.

🧱 OS or Firewall Blocks DNS Redirection #

Some mobile devices, or browsers with custom DNS settings (e.g., DNS over HTTPS), won’t honor standard DNS-based captive portal techniques.

These users will need a manual redirect or QR code.

Practical Fixes #

✅ Ensure Web and DNS Servers Are Initialized #

Your setup() function should include:

WiFi.softAP("ESP32_Setup");

dnsServer.start(53, "*", WiFi.softAPIP());
server.on("/", handleRoot);
server.begin();

Avoid calling server.begin() before enabling AP mode.

✅ Add Manual Fallback Instruction #

Display this in Serial Monitor or via external screen:

Please connect to "ESP32_Setup" and go to http://192.168.4.1

You can also serve a QR code for http://192.168.4.1 to make access easier.

✅ Handle Sleep/Reset Correctly #

If the ESP32 goes into deep sleep or soft reset, re-run WiFi.softAP(), dnsServer.start(), and server.begin() after wake-up.

Bonus Tips #

• Avoid using esp32.local inside captive portals - .local requires mDNS and won’t work reliably without internet.

• Disable AP isolation or client separation in router-based captive networks.

• Consider using WiFiManager, which implements many best practices for ESP32 captive portals.

Conclusion #

Captive portals are fragile because they rely on:

• The device OS recognizing the AP

• DNS hijacking working as expected

• Users accessing the correct page

By ensuring both the DNS and HTTP servers are running, avoiding HTTPS redirects, and guiding users to the AP IP (192.168.4.1), you can make your ESP32 captive portal far more reliable across all platforms.