UniFi guest Wi-Fi and captive portal troubleshooting
A field guide for guest SSIDs, VLAN isolation, DNS, redirects, vouchers, captive portal authorizations and the symptoms users actually report.
Kareem Schultz
Technology enthusiast & systems builder · Guyana
Jump to a section
Start with the topology and the symptom
A guest Wi-Fi problem may be an RF connection issue, a missing VLAN on a switch port, DHCP or DNS failure, a portal redirect issue, or an authentication problem. These are different paths. Record the SSID, site, AP, client OS, controller version and the first failing stage.
UniFi’s current hotspot guidance allows a portal on a Wi-Fi SSID or network/VLAN, with password, vouchers, RADIUS and external portal options depending on configuration. Check installed release documentation before following screenshots from older controller versions.
The four-stage client journey
The client must first associate, receive usable addressing, resolve permitted destinations and reach the portal. Only after the authentication flow does the gateway or authorization service permit broader access. A successful splash page does not prove DNS, isolation or post-authorization routing is correct.
| Stage | Symptom | Check |
|---|---|---|
| Join | Cannot connect or receives no address | AP radio, SSID/VLAN tagging, DHCP |
| Detect portal | Splash never appears | Captive-network detection, DNS, pre-auth routes |
| Authorize | Voucher rejected / loops | Expiry, code policy, backend and client ID |
| After login | Portal succeeds but internet fails | WAN, DNS, hotspot zone and guest policy |
Isolation is independent of the splash screen
A captive portal is not sufficient by itself to prevent guests reaching other clients or management interfaces. UniFi supports network isolation, gateway zone-based policy, switch ACLs and AP client isolation at different layers. Test permitted and denied flows from a guest device.
Vouchers, external portals and HTTPS
Record which authentication option is configured and whether a voucher is single-use, time-limited or has bandwidth quotas. For an external portal, ensure the pre-authorization path can reach the domain and the return authorization maps to the correct client. HTTPS hostname mismatch, certificate issues or blocked DNS can cause redirect loops.
Mobile-specific tests and accessibility
iOS and Android may display captive-network mini-browsers instead of a full browser. Test both, plus ordinary browsers after joining the SSID. Check that the splash works with reduced motion, keyboard navigation, accessible labels and a clear error/retry state.
A print-friendly voucher should not depend on an embedded frame or a pop-up that mobile browsers block. The public-facing portal should explain usage limits and privacy practices.
FAQ and handover
If a user is already authorized yet sees a splash again, check captive detection, session expiry and network re-association before changing gateway policy. If only one location fails, compare switch uplink and AP-to-VLAN paths. Handover should include sanitized diagrams, owner access, backup and tested restoration.
Frequently asked questions
Sources & further reading
These links provide the technical basis for the article. Check upstream advisories and documentation for revisions.