Ubiquiti UniFi captive portal troubleshooting: external portal, hotspot and walled garden checklist
Use this checklist to find out why your Ubiquiti UniFi captive portal is not working and fix it. You will match the symptom to one of six causes, run two quick tests, and correct the external portal server, pre-authorization access, guest subnet restrictions, HTTPS redirects, controller reachability or client settings.
Video overview
Part of our core series: Captive portal guide →
A UniFi captive portal fails for one of five reasons. The external portal server address is wrong, or the portal and login domains are missing from pre-authorization access. Guest isolation may block the portal host. The redirect may use HTTP to an IP address. Or the console is unreachable. Check each in turn, then test from a client.
What does a UniFi captive portal that is not working look like?
Most faults show up as one of four symptoms. Naming the symptom first narrows the cause before you open the UniFi Network application.
- No portal at all. The device joins the guest SSID and gets an IP address, but no login prompt appears. The cell phone may report "no internet" or show connected with no traffic.
- A blank or endlessly loading page. The Captive Network Assistant (CNA) opens, but the splash page never renders. The CNA is the small browser your operating system launches on a captive network.
- A certificate warning. Laptops show "Your connection is not private" before the login page. Guests must click through a warning to continue.
- A partial portal. The splash page loads, but a social login or payment button spins, fails or loops back.
Purple's Captive Portal support article explains the CNA in more detail. The CNA checks a predefined domain to test whether the internet is reachable. It then notifies the device, launches a browser and confirms an "online" status. When any part of that chain breaks, your guests see one of the symptoms above.
This guide assumes your UniFi hotspot portal or external portal is already configured. It is a fault-finding checklist, not a setup guide.
What usually causes a UniFi captive portal to fail?
Six causes account for most UniFi guest portal troubleshooting cases.
- Wrong external portal server setting. The address points to an old host, a typo or a server the gateway cannot reach.
- Incomplete pre-authorization access. UniFi labels this setting "Pre-Authorization Access". It is UniFi's walled garden: the hosts and subnets a guest can reach before logging in. If the portal, its assets or a social login provider are missing, the page stays blank or partial.
- Guest network restrictions. UniFi guest networks block private address ranges. A portal server or DNS server on an internal subnet becomes unreachable.
- HTTPS and hostname redirect mismatches. An HTTPS redirect to an IP address, or to a hostname with no matching certificate, triggers browser warnings.
- Controller or console reachability. Self-hosted UniFi Network Servers and cloud consoles must stay reachable. With an external portal, the controller must also reach the RADIUS server that completes the login.
- Client-side interference. VPNs, custom DNS settings or a dismissed CNA notification stop the redirect on that device.
How do you work out which UniFi captive portal fault you have?
Start with the symptom, then run the first check in the table before you change any setting.
| Symptom | Most likely cause | First check | Fix |
|---|---|---|---|
| No portal, no prompt | DNS unreachable or CNA probe blocked | Can the client resolve a public hostname before login? | Hand out a DNS server outside the blocked private ranges, or allow it in pre-authorization access |
| Blank or endlessly loading page | Portal host or assets missing from pre-authorization access | Does the portal hostname resolve and load from a guest device? | Add the portal host, its asset domains and its subnet to pre-authorization access |
| Certificate warning on laptops | HTTPS redirect to an IP address or mismatched hostname | What URL appears in the address bar at the warning? | Disable HTTPS redirection, or redirect by hostname with a publicly trusted certificate matching that hostname |
| Social login button spins or fails | Identity provider domains missing | Which domain fails in the browser's network view? | Add every domain the provider's login page loads |
| Payment step fails | Payment gateway domains missing | Does the payment page load at all? | Add the payment provider's hosts to pre-authorization access |
| Portal loads, login never completes | RADIUS or controller unreachable | Do authentication attempts appear in the controller events? | Restore controller reachability and confirm the RADIUS details match your portal provider |
| One device fails, others work | Client-side VPN, custom DNS or dismissed CNA | Does neverssl.com redirect on that device? | Disable the VPN or custom DNS, forget the network and rejoin |
Two quick tests separate most faults. First, browse to neverssl.com on a connected but unauthenticated device. Purple's support team recommends this site because it avoids problems with SSL redirects. If neverssl.com redirects to your portal, the redirect works and the fault sits in pre-authorization access or the portal itself. If it does not redirect, look at DNS, the external portal server setting or the controller.
Second, check the client entry in the UniFi Network application. The client list and events show whether the device is on the guest network and whether it has authorized. A device marked as authorized but still showing the portal points to a client-side cache or CNA issue.
How do you fix each UniFi captive portal cause?
Purple does not reproduce UniFi menu paths here, because they change between UniFi Network releases. Use Ubiquiti's current documentation for the exact location of each setting.
External portal server
Confirm the external portal server value matches what your portal provider specifies. A single wrong character sends every guest to a dead host. If you moved portal providers, remove the old address rather than leaving it alongside the new one.
When you use Purple, the splash page servers collect guest details and issue a one-time login. The controller passes that login to Purple's RADIUS server to complete authentication. RADIUS is the protocol network equipment uses to check credentials against a central server. If the portal loads but login fails, check the RADIUS profile next.
Pre-authorization access for the portal, social login and payment domains
This is the most common fix. Add these entries to pre-authorization access:
- The portal server host and any subnet it lives on.
- Every domain the splash page loads, including fonts, images and scripts from content delivery networks.
- Each social login provider's authentication domains, if you offer Facebook, Google or Apple sign-in.
- Your payment gateway's hosts, if you charge for premium access.
Open the splash page from a laptop on an unrestricted network, with the browser's developer tools showing network requests. Every domain listed there must be reachable before login. Where your UniFi Network version accepts IP entries only, re-check them whenever a provider changes its addresses.
Guest network isolation and blocked subnets
Guest isolation does not block the captive portal on its own. Client device isolation stops guest devices from talking to each other. The guest network's subnet restrictions block private address ranges, and those restrictions catch internal portal or DNS servers.
If your portal server or DNS resolver sits on an internal subnet, add that specific host to pre-authorization access. A cleaner pattern is to hand guests a public DNS resolver and host the portal on a public address.
HTTPS and hostname redirect options
Modern browsers expect HTTPS for login pages. Purple's Cisco WLC certificate article describes the same pattern on Cisco hardware. A redirect to an HTTP address such as a bare IP triggers a security warning, and guests must click through it.
The fix follows the same principle on UniFi. Either leave HTTPS redirection off and let the CNA use HTTP, or redirect by hostname. A hostname redirect needs a publicly trusted SSL/TLS certificate, and the hostname must match the certificate's Common Name. A self-signed certificate or a mismatched name brings the warning straight back.
Controller reachability for self-hosted and cloud consoles
For a self-hosted UniFi Network Server, confirm the server is running and reachable from your gateway and access points. Check firewall rules between sites if the server sits in a head office or data center. For cloud consoles, confirm the console shows online and the gateway is adopted. Then confirm outbound traffic to your RADIUS server is allowed.
Client checks
Ask the guest to forget the network and rejoin. Disable any VPN or custom DNS setting, which can bypass the redirect entirely. If the CNA notification was missed, open a browser and go to neverssl.com. On Android, tapping the "you may need to log in" notification launches the CNA browser session.
Got questions about your specific setup?
Our team works with venue operators, IT managers, and network engineers across 80,000 venues. Book a 20-minute call and we will show you how others like you solved it.
Worked examples from hospitality, retail and events
These worked examples show how the checklist plays out at venue level.
A 200-room hotel with a blank splash page
Situation. A hotel ran a self-hosted UniFi Network Server and an external portal. After a network change, guests on the guest SSID saw a blank page. Front desk staff logged around a dozen complaints per night.
What was done. neverssl.com did not redirect, so the team checked DNS first. The guest VLAN's DHCP scope was handing out an internal DNS server on a private subnet. Guest restrictions blocked that subnet. The team switched the guest scope to a public resolver.
Outcome. Portal redirects worked on the next connection. Front desk logged no further WiFi complaints that week.
A 40-store retail chain with a stalled social login
Situation. A retail chain added social sign-in to its splash page. The email form worked, but the social button spun indefinitely in every store.
What was done. The team opened the splash page with developer tools and listed every domain the provider's login loaded. They added those to pre-authorization access in one pilot store, tested on Android and iOS, then rolled the change to all 40 stores.
Outcome. Social sign-in completed in all 40 stores. The team now retests the pilot store after each provider update.
A conference center with certificate warnings
Situation. Delegates on laptops saw "Your connection is not private" before the portal. Phones worked through the CNA, so the fault looked intermittent.
What was done. The address bar showed an HTTPS redirect to an IP address. The team disabled HTTPS redirection until a publicly trusted certificate matching the redirect hostname was in place.
Outcome. The warning disappeared on laptops. The event helpdesk stopped receiving portal tickets for the rest of the conference.
How do you stop the UniFi captive portal failing again?
- Keep a pre-authorization register. List every host and subnet, why it is there and who owns it. Review it when you add a login method or payment provider.
- Test after every change. Use one Android phone, one iPhone and one laptop. Confirm neverssl.com redirects and login completes.
- Track certificate expiry. An expired certificate on a hostname redirect produces the same warning as no certificate.
- Monitor the controller. Alert on a self-hosted server going offline before guests notice.
- Run an open guest network. Purple recommends open guest networks because familiarity reduces friction at login.
The same discipline applies on other vendors. Purple's HPE Aruba captive portal troubleshooting guide and Cisco Meraki captive portal troubleshooting guide follow the same checklist for those platforms.
Frequently asked questions
Does Purple work with the Ubiquiti UniFi access points we already own?
Yes, Purple runs on Ubiquiti UniFi as an external portal and RADIUS service, so you keep your existing access points. Purple is hardware-agnostic and also supports Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist, Cambium, Extreme and Fortinet. That matters for multi-site properties with mixed hardware, because one Guest WiFi configuration covers every vendor. Purple's platform runs across 80,000+ live venues, according to Purple's own data.
Can we keep a self-hosted UniFi Network Server with an external portal?
Yes, a self-hosted UniFi Network Server works with an external portal, provided it stays reachable. The gateway and access points must reach the server, and the server must reach your portal provider's RADIUS service. Check firewall rules between sites if the server sits in a corporate headquarters. Cloud consoles remove the hosting task but still need outbound access to RADIUS.
Should our UniFi guest network be open or password-protected?
Open is the recommended choice for guest access. Purple recommends providing Guest WiFi over an open network because it is now the standard convention and reduces friction at login. The captive portal still controls access, collects conscious-choice opt-ins and issues each guest a one-time login. Password-protected guest networks add a step and cause more front-desk queries.
Do we need to buy an SSL certificate for our captive portal?
Yes, if you redirect guests over HTTPS or by hostname. Browsers expect a publicly trusted certificate, and the redirect hostname must match the certificate's Common Name. Without one, laptops show a security warning before the portal loads. If you cannot maintain a certificate, leave HTTPS redirection off and let the device's CNA use an HTTP redirect instead.
How does moving to Purple affect our GDPR position?
Purple helps you meet CCPA/CPRA rather than adding risk. Purple holds ISO 27001, GDPR, CCPA and Cyber Essentials certifications, and the splash page records conscious-choice opt-ins for marketing consent. The first-party data you collect stays tied to the consent each guest gave. Your own privacy notice and retention policy still apply, so review both before launch.
How much effort is it to move from the built-in UniFi hotspot to Purple?
Moving to Purple is a configuration change, not a hardware project. You point the external portal server and RADIUS settings at Purple, then update pre-authorization access for the splash page domains. Purple layers on top of your existing UniFi infrastructure, so there is no rip and replace. Test one site first, then copy the settings across your property estate.
Can Purple handle guest login at high-volume venues?
Yes, Purple processed 440 million logins in 2024, according to Purple's own data. That volume spans hotels, retail, trains and healthcare sites with heavy peaks. On UniFi, capacity at the portal is rarely the bottleneck. DNS reachability and complete pre-authorization access matter more, so apply this checklist before a large event.
Key Definitions
Captive portal
A web page that intercepts a newly connected client and requires an action, such as login or consent, before granting wider network access. The IETF describes the architecture in RFC 8952, covering detection, the enforcement device and the portal server.
You meet it as the UniFi hotspot portal or an external portal. When any step of the redirect chain breaks, guests see no portal, a blank page or a warning.
Captive Network Assistant (CNA)
The small browser an operating system launches on a captive network. It probes a predefined domain to test whether the internet is reachable, notifies the device, opens the login page and confirms an online status.
A blocked probe or a dismissed CNA notification is why one device fails while others work. Opening neverssl.com in a browser restarts the redirect manually.
Pre-authorization access (walled garden)
UniFi's "Pre-Authorization Access" setting: an allow list of hosts and subnets a guest can reach before authenticating. It is enforced at the gateway ahead of captive portal login.
This is the most common fix. Missing portal, asset, social login or payment domains produce blank or partial splash pages.
External portal server
The UniFi setting that sends unauthenticated guests to a third-party splash page instead of the built-in hotspot portal. The address must resolve and be reachable from the gateway.
A typo or a leftover address from a previous provider sends every guest to a dead host. Remove old entries when you change provider.
RADIUS
Remote Authentication Dial-In User Service, defined in IETF RFC 2865. It carries access requests from network equipment to a central server that accepts or rejects credentials.
With Purple, the controller passes the one-time login to Purple's RADIUS server. If the portal loads but login never completes, check RADIUS details and outbound reachability.
Client device isolation
An access point feature that blocks layer 2 forwarding between wireless clients on the same SSID, so guest devices cannot reach each other. It is a vendor feature rather than part of IEEE 802.11.
Isolation alone does not block the portal. The guest network's private subnet restrictions are what catch internal portal or DNS servers.
VLAN
A virtual LAN defined by IEEE 802.1Q, which tags Ethernet frames to separate traffic into logical networks over shared switching infrastructure.
The guest SSID typically maps to a guest VLAN with its own DHCP scope. The scope's DNS setting decides whether guests can resolve hostnames before login.
DHCP scope
The address pool and options a DHCP server hands to clients, defined in IETF RFC 2131. Options include the default gateway and the DNS servers the client should use.
A guest scope handing out an internal DNS server on a blocked private subnet stops the portal appearing at all.
SSL/TLS certificate Common Name
An X.509 certificate, profiled for the internet in IETF RFC 5280, binds a public key to a subject. Browsers check that the hostname they connect to matches the names in the certificate.
An HTTPS redirect to a bare IP, a mismatched hostname or a self-signed certificate triggers "Your connection is not private" on laptops.
Conscious-choice opt-ins
Purple's term for marketing consent a guest actively gives on the splash page. Under CCPA/CPRA, consent must be freely given, specific, informed and demonstrable.
The splash page records these opt-ins, so first-party data stays tied to the consent each guest gave. Your own privacy notice and retention policy still apply.
Worked Examples
A 200-room hotel runs a self-hosted UniFi Network Server with an external portal. After a network change, guests on the guest SSID see a blank page and front desk staff log around a dozen complaints per night. What fixed it?
The team browsed to neverssl.com on an unauthenticated device and it did not redirect, which pointed to DNS, the portal server setting or the controller. They checked DNS first. The guest VLAN's DHCP scope was handing out an internal DNS server on a private subnet, and UniFi guest restrictions block private address ranges. Guests therefore could not resolve hostnames before login. The team switched the guest scope to a public resolver. Portal redirects worked on the next connection, and the front desk logged no further WiFi complaints that week.
A 40-store retail chain adds social sign-in to its splash page. The email form works, but the social login button spins indefinitely in every store. How did the team resolve it?
A spinning social button means the identity provider's domains are missing from pre-authorization access. The team opened the splash page on a laptop with the browser's developer tools showing network requests. They listed every domain the provider's login page loaded and added those entries to pre-authorization access in one pilot store. They tested on Android and iOS before rolling the change out to all 40 stores. Social sign-in then completed everywhere. The team now retests the pilot store after each provider update, because provider domains and addresses change.
At a conference center, delegates on laptops see "Your connection is not private" before the portal, while cell phones work through the CNA. The fault looks intermittent. What was the cause and the fix?
The team read the URL in the address bar at the warning. It showed an HTTPS redirect to an IP address, which no publicly trusted certificate can match. Cell phones worked because the CNA handled the redirect differently, which made the fault look intermittent. The team disabled HTTPS redirection until a publicly trusted certificate matching the redirect hostname was in place. The warning disappeared on laptops, and the event help desk stopped receiving portal tickets for the rest of the conference.
Frequently asked questions
Does Purple work with the Ubiquiti UniFi access points we already own?
Yes, Purple runs on Ubiquiti UniFi as an external portal and RADIUS service, so you keep your existing access points. Purple is hardware-agnostic and also supports Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist, Cambium, Extreme and Fortinet. That matters for multi-site properties with mixed hardware, because one Guest WiFi configuration covers every vendor. Purple's platform runs across 80,000+ live venues, according to Purple's own data.
Can we keep a self-hosted UniFi Network Server with an external portal?
Yes, a self-hosted UniFi Network Server works with an external portal, provided it stays reachable. The gateway and access points must reach the server, and the server must reach your portal provider's RADIUS service. Check firewall rules between sites if the server sits in a corporate headquarters. Cloud consoles remove the hosting task but still need outbound access to RADIUS.
Should our UniFi guest network be open or password-protected?
Open is the recommended choice for guest access. Purple recommends providing Guest WiFi over an open network because it is now the standard convention and reduces friction at login. The captive portal still controls access, collects conscious-choice opt-ins and issues each guest a one-time login. Password-protected guest networks add a step and cause more front-desk queries.
Do we need to buy an SSL certificate for our captive portal?
Yes, if you redirect guests over HTTPS or by hostname. Browsers expect a publicly trusted certificate, and the redirect hostname must match the certificate's Common Name. Without one, laptops show a security warning before the portal loads. If you cannot maintain a certificate, leave HTTPS redirection off and let the device's CNA use an HTTP redirect instead.
How does moving to Purple affect our CCPA/CPRA position?
Purple helps you meet CCPA/CPRA rather than adding risk. Purple holds ISO 27001, GDPR, CCPA and Cyber Essentials certifications, and the splash page records conscious-choice opt-ins for marketing consent. The first-party data you collect stays tied to the consent each guest gave. Your own privacy notice and retention policy still apply, so review both before launch.
How much effort is it to move from the built-in UniFi hotspot to Purple?
Moving to Purple is a configuration change, not a hardware project. You point the external portal server and RADIUS settings at Purple, then update pre-authorization access for the splash page domains. Purple layers on top of your existing UniFi infrastructure, so there is no rip and replace. Test one site first, then copy the settings across your estate.
Can Purple handle guest login at high-volume venues?
Yes, Purple processed 440 million logins in 2024, according to Purple's own data. That volume spans [hotels](/industries/hotels), [retail](/industries/retail), [trains](/industries/trains) and [healthcare](/industries/healthcare) sites with heavy peaks. On UniFi, capacity at the portal is rarely the bottleneck. DNS reachability and complete pre-authorization access matter more, so apply this checklist before a large event.
Sources
- Purple support: Captive Portal
- Purple support: Cisco WLC captive portal certificate setup
- Ubiquiti UniFi help centre
- IETF RFC 2865: Remote Authentication Dial In User Service (RADIUS)
- IETF RFC 5280: Internet X.509 public key infrastructure certificate profile
- Purple guide: HPE Aruba captive portal troubleshooting
- Purple guide: Cisco Meraki captive portal troubleshooting
Continue reading in this series
HPE Aruba captive portal troubleshooting: redirect, certificate and walled garden checklist
Use this checklist to diagnose a failing HPE Aruba captive portal from the symptom you see: no redirect, a certificate warning or a guest who is never released. You can then trace the fault to DNS, DHCP, the walled garden, the redirect URL, the certificate or RADIUS. Finally, apply the fix on Instant APs, Aruba Central or a mobility controller.
Cisco Meraki captive portal troubleshooting: splash page, walled garden and RADIUS checklist
Use this checklist to identify which of four faults is breaking your Cisco Meraki captive portal: splash page type, walled garden, grant URL hand-off or RADIUS reachability. You will be able to read the Meraki event log, match the symptom to its cause and apply the right fix without repeating SSID setup.
Captive portal login on Android: a deployment checklist for Cisco Meraki, HPE Aruba and Ubiquiti UniFi
Use this checklist to get the Android sign-in notification appearing reliably on Cisco Meraki, HPE Aruba and Ubiquiti UniFi. You will scope a tight walled garden, block traffic until sign-on, secure the login page with HTTPS and keep DNS working. You will also choose a session timeout, decide on DHCP option 114 and trace each guest symptom to its fix.
Got questions about your specific setup?
Our team works with venue operators, IT managers, and network engineers across 80,000 venues. Book a 20-minute call and we will show you how others like you solved it.