Captive
Sign inStart free trial

Troubleshooting

Endless WiFi spinner, portal never loads

The device joins the guest WLAN, the captive-portal check spins forever, and no request reaches the portal. Cause: the gateway's pre-auth walled garden doesn't allow the portal's actual IP. Hosting providers rotate IPs per DNS query, so a single exact-IP entry breaks whenever the device's resolver returns a sibling address.

Fix: re-run Auto-configure portal — Captive whitelists the /24 of every resolved portal address plus the hostname itself. (Direct connections only; on the UniFi cloud connection update the pre-authorization allowances in the UniFi console by hand — see the quickstart.)

"We saved your email but couldn't unlock the connection"

The portal captured the email but couldn't reach your console to authorize the device. Site → Test connection tells you immediately. On the UniFi cloud connection, check that the console is online at unifi.ui.com and the API key is still valid. On a direct connection, check that the console is reachable from the internet (port forward / VPN up, public IP unchanged) and that the local admin credentials are still valid.

Guests connect without ever seeing the portal

Devices authorized under a previous portal (or earlier in the session window) stay authorized until their session expires — only new or expired devices see the portal. To re-test a device you can toggle its WiFi off/on if it uses a private (rotating) MAC address, forget the network, or shorten the guest session length in site settings.

The portal replaced my old portal on every guest SSID at once

That's how UniFi works: the hotspot portal is configured per UniFi site, not per SSID. Auto-configure cuts over every WLAN flagged as a guest network. Unflag any SSID that shouldn't use the portal.

The mini-browser closes before my landing page shows

Apple's Captive Network Assistant may auto-dismiss the moment the device is online — before or during the post-auth redirect. That's the operating system, not a bug; the guest is connected. The portal shows a Continue button for guests who keep the window open.

Login to the console fails

  • The admin must be a local account (not a Ubiquiti cloud login).
  • Two-factor must be off for that account.
  • The account needs Network application permissions.