When a UniFi captive portal fails, the visible symptom is usually simple: the guest joins WiFi but never sees the sign-in page. The cause may be the SSID configuration, DNS, pre-authorization rules, portal reachability, client detection, or the final authorization request.
Use this sequence to isolate the failure instead of changing several settings at once.
1. Confirm the guest network and SSID
- Confirm the device is connected to the intended guest SSID.
- Confirm the SSID is mapped to the intended guest network or VLAN.
- Confirm Hotspot Portal or Captive Portal is enabled on that SSID.
- Confirm the AP has received the latest configuration.
- Confirm guest traffic is isolated from internal networks.
UniFi supports captive portals on a WiFi SSID or an entire hotspot network. Public guest networks should also use appropriate network and client isolation.
2. Trigger the portal with an HTTP request
Captive-portal detection varies between operating systems. Open a simple HTTP page in a browser after joining the guest network. Do not test only by opening an HTTPS site.
If HTTP triggers the portal but HTTPS does not, the network may be working as designed. The captive portal must first intercept a request that can be redirected safely.
3. Check DNS and portal reachability
The guest device must be able to resolve and reach the portal before authorization. Check:
- DNS resolution for the portal hostname
- A valid public HTTPS certificate
- Correct hostname and redirect URL
- Firewall rules between the guest network and portal
- Whether required CSS, JavaScript, fonts, and images use separate blocked domains
UniFi’s port reference identifies DNS as required for guest portal redirection. It also lists TCP 8880–8882 for HTTP hotspot redirection and TCP 8843 for HTTPS hotspot redirection in relevant deployments.
4. Check pre-authorization access
If the page shell loads but looks broken, the guest may be able to reach the HTML page but not its assets. Add only the required portal domains to the pre-authorization or walled-garden configuration.
Test each required hostname from a fresh guest device. Avoid allowing broad internet access before authorization.
5. If using an external portal, inspect the redirect parameters
UniFi’s External Hotspot API documentation shows that the external portal can receive parameters including:
- AP address
- Client address
- Original destination URL
- SSID
- Timestamp
Log these values safely during testing. Confirm that the portal is receiving the request for every test client and that the original destination is preserved.
6. Separate client lookup from authorization
An external portal commonly needs to identify the UniFi client before authorizing it. Treat these as separate checks:
- Identify the correct UniFi site.
- Find the client using the received client address or another supported identifier.
- Confirm the returned client ID belongs to the current test device.
- Submit the guest-authorization action.
- Inspect the API response.
- Confirm the client status changes to authorized.
Do not redirect the guest before authorization succeeds. Otherwise, the guest may see a success page while remaining offline.
7. If authorization succeeds but browsing fails
Check the following:
- Guest VLAN and gateway assignment
- Firewall and isolation rules
- DNS after authorization
- The post-login redirect URL
- Whether the device is still using the captive-network assistant
- Whether the test device was previously authorized
Forget the guest network and repeat the test with a clean client state.
8. Test more than one device and AP
Run the complete flow on:
- iPhone or iPad
- Android phone
- Laptop
- At least two APs, if available
A portal that works in a normal browser may still fail in an operating system’s captive assistant. Keep the first page lightweight and make the successful authorization response obvious.
9. Capturing email responsibly
If the goal is contact capture, request only information needed for the stated purpose. Explain why the email is requested, link to the privacy notice, and use a separate marketing-consent control where appropriate.
This guide is technical information, not legal advice. Review the privacy and electronic-marketing requirements that apply to your venue and jurisdiction.
10. A hosted alternative
If you do not want to maintain the external portal, API integration, consent flow, and troubleshooting process yourself, LiquidEdge provides a hosted WiFi marketing portal for businesses operating a hosted UniFi controller.
Create a free LiquidEdge account, connect one UniFi controller, choose one site and AP, and launch your first portal.
The permanent free plan is designed for one site and one access point. Paid expansion is available when you need more sites or APs, higher contact limits, richer analytics, exports, integrations, branding removal, or marketing automation.
Quick decision tree
- No portal redirect: check SSID, Hotspot Portal, DNS, HTTP testing, and UniFi redirection ports.
- Portal shell loads but is broken: check pre-authorization domains and blocked assets.
- Form submits but guest remains offline: check client lookup, site ID, API response, and authorization status.
- Authorized but no browsing: check VLAN, firewall, DNS, and post-login redirect.
- Works on one device only: repeat with fresh client state and multiple operating systems.