UniFi Captive Portal Not Working: Troubleshooting Checklist

UniFi Captive Portal Not Working? A Practical Activation Checklist

Use this guide to troubleshoot a UniFi captive portal or external guest portal that appears configured but does not produce a working guest experience.

Setup checklist

Confirm the intended UniFi Network site is selected and reachable.
Map the guest network to the intended SSID or VLAN.
Enable Hotspot Portal / Captive Portal.
Isolate guest traffic from internal networks and configure client isolation where appropriate. (help.ui.com)
Confirm the SSID is assigned to an online access point.
Confirm controller and portal reachability.
Verify the external portal URL and redirect parameters.
Test with a real device and a controlled network state.

Decision tree

SSID not visible

Check AP assignment, AP health, and VLAN tagging. Incorrect VLAN tagging is a common cause of clients being unable to join WiFi. (help.ui.com)

SSID visible, but access fails

Confirm addressing, routing, firewall rules, and guest isolation. Test a second device.

No portal appears

Verify Captive Portal is enabled on the correct SSID or network. Open a normal HTTP website to trigger redirection.

For an external portal, confirm that the redirect reaches the portal server and that it can process the authorization request. UniFi external-hotspot clients begin in a pre-authorization state before the external portal authorizes them. (help.ui.com)

Portal loads, but authorization fails

Check site, client, and redirect parameters. Inspect controller and portal logs using a shared UTC timestamp. A page load is not proof of authorization.

Portal telemetry exists, but guests still cannot connect

Separate:

Portal telemetry: creation, queue, or publication events.
Network state: enabled SSID, online AP, and correct routing.
Guest evidence: a real device joins, completes the flow, and loads an internet page.

Only the third check demonstrates a genuine guest experience.

LiquidEdge setup path

LiquidEdge is designed for businesses operating a hosted, publicly reachable UniFi controller. The current capability check reports free-account creation available on September 10, 2026. The active free account includes one site, one access point, limited contact collection, and no payment card requirement; withdraw these claims if the capability check fails closed.

Create a free LiquidEdge account when your controller is ready, then validate controller connection, site/AP import, portal configuration, enabled SSID, and a genuine guest login.

Follow-up template

Test timestamp UTC:
UniFi Network version:
Controller hosting/reachability:
Site:
SSID/network:
AP tested:
Client device and OS:
Observed stage:
Portal telemetry:
SSID/AP state:
Guest-login result:
Exact error or redirect:
Request/correlation ID:

Never include passwords, API keys, tokens, or full private addresses.

Measurement

Track article CTA clicks, account creation, controller connection, portal creation, portal publication, and first genuine guest login as separate events. For the live-journey investigation, use a 14-day window or at least 10 eligible accounts. Keep account and venue populations separate.

Escalation

Escalate when a verified account has imported a site/AP but cannot complete portal setup, when publication appears complete but controlled guest access fails, when the problem reproduces across clients, or when portal telemetry conflicts with observed SSID state.