When your UniFi captive portal stops working, guests can't access the internet and your business suffers frustrated customers. Most captive portal issues stem from guest device detection problems rather than network misconfigurations, but systematic troubleshooting helps identify the root cause quickly, whether it's the device, DNS settings, firewall rules, or controller configuration.
This guide provides a step-by-step debugging process for UniFi captive portal issues, starting with the most common causes and progressing to more technical diagnostics. Follow each step in order until the issue is resolved.
What you'll troubleshoot:
Guest device internet detection and captive portal popup failures
DNS resolution and network connectivity issues
UniFi guest policy and firewall configuration
Access point and controller connectivity problems
What you'll need:
Admin access to your UniFi controller
Guest device experiencing the issue (for testing)
Terminal/command prompt access (for advanced debugging)
Most common cause: Guest device fails to detect the captive portal (90% of cases). Always start with device-level troubleshooting before checking network configuration.
This post is about how to debug an UniFi captive portal issue. The process includes testing connectivity, looking at the controller, and at times rebooting the APs.
Unfortunately, this can be a frustrating problem to solve, especially when it happens to a high-value Guest who really wants the internet!
It's almost always the Guest Device!
The device Guest is using to connect the network is to blame in most cases. It's the device that, when connecting to a WiFi network tries to check if it can access the internet. If it can't popups a browser/application that loads the splash page.
However, this process of internet detection is not reliable and fails at times. When it fails, the device won't have internet access neither would it pop up the captive portal.
Follow the below steps to debug the root cause of this. Go to the next step only if the previous one fails.
Step1: Visit a non-HTTPS site on the Guest device
Open up the browser on the guest device and visit http://neverssl.com/ this should force your device to open up the splash page.
Step2: Remove Network Profile From device and reconnect
Forget the wireless network from your device and connect again. This would help if the issue was caused by the guest's device not being able to detect the Guest wifi.
Step 3: Check the DNS and walled garden
If you reach here, you might want to have a laptop or MacBook to debug the issue a bit more deeply.
Open up a terminal on the Guest device and try to ping app.spotipo.com
If the domain can't be resolved, then there could be some issue with DNS on your network, or could be that another firewall is blocking DNS packets.
If you are able to resolve the domain, but the ping fails. Please check the Guest Policy settings.
Step 4: Check the Guest Policy settings
Login to your UniFi controller and navigate to Guest policy in the legacy UI.
Here check that:
The external portal server address is selected
Custom Portal IPv4 address is correct
Pre-Authorization access has the IP of our load balancer
Step 5: Check Networks
Navigate to the Networks tab, if you had a dedicated VLAN setup for the Hotspot, it should be of type 'Corporate' not 'Guest'. Guest networks are for enabling portals on wired connections
Step 6: Restart the AP and controller
As the last step, please try to restart the Access Points and Unifi controller. It could be that either of those is having issues and not able to redirect Guests properly.
Step 7: Contact Support
If none of the above steps helps, please contact spotipo support. Either via the chat wizard or by sending an email to support [at] spotipo [dot] com
Your UniFi Captive Portal Should Now Work
After following these debugging steps systematically, you should have identified and resolved the captive portal issue. Most problems are solved by forcing the device to load a non-HTTPS site or forgetting and reconnecting to the network.
Quick troubleshooting checklist:
Visit http://neverssl.com on guest device
Forget network and reconnect
Verify DNS resolves app.spotipo.com
Check guest policy settings (external portal, correct IP, pre-auth access)
Verify network type is Corporate (not Guest) for VLAN hotspots
Restart APs and controller if needed
When to contact support: If you've completed all seven debugging steps and the captive portal still doesn't work, the issue may be unique to your network configuration. Contact Spotipo support via live chat or email [email protected] with details about which steps you've completed and any error messages observed.