Ruckus captive portal troubleshooting: WISPr redirect, hotspot and walled garden checklist

Most Ruckus captive portal faults trace to five places: the hotspot (WISPr) logon URL and start page, missing walled garden entries for the portal and its assets, a mismatched northbound portal interface password, RADIUS authentication or accounting failures, and HTTPS redirect certificate warnings. Check them in that order, using the client's event history on SmartZone, Ruckus One or Unleashed.

What does a broken Ruckus captive portal look like?

A Ruckus hotspot service uses WISPr (Wireless Internet Service Provider roaming). This is a framework in which the controller holds an unauthenticated guest behind a captive portal until an external system approves them. A captive portal is the splash page a guest completes before they reach the internet. When the chain breaks, the guest sees one of six symptoms:

• No redirect at all. The device joins the SSID and receives an IP address, but no login prompt appears and the browser times out.
• A blank or half-drawn splash page. The prompt opens, but logos, fonts, scripts or social login buttons fail to load.
• A certificate warning before the portal. The browser shows "Your connection is not private" or similar, and the guest must click through.
• A login loop. The guest completes the form and lands back on the splash page, still offline.
• No prompt, yet no internet. The device reports it is online, so the Captive Network Assistant never opens.
• Online, but no session data. Guests browse normally, yet logins and session durations never reach your reporting.

The last two symptoms are easy to miss, because nobody calls the help desk. You notice them later, when your guest data stops growing.

What usually causes Ruckus captive portal failures?

It helps to know the sequence first. Purple's Captive Portal support article sets it out. The controller manages the WiFi interaction with Purple's splash page servers. Those servers collect the guest's details and issue a one-time login. The controller then passes that login to Purple's RADIUS server to complete access. RADIUS (Remote Authentication Dial-In User Service, RFC 2865) is the protocol that authenticates the session. RADIUS accounting (RFC 2866) reports the session afterwards.

Each step has its own failure mode.

Hotspot service redirect and start-page settings

The hotspot service holds the external logon URL and the start page. The logon URL is where unauthenticated guests are sent. The start page is where they land after login. A typo, a stale URL after a portal change, or the wrong hotspot service attached to the WLAN all stop the redirect. A start page pointing at a blocked or retired URL makes a successful login look like a failure.

Walled garden gaps

The walled garden is the list of destinations an unauthenticated guest can reach before login. It must include the portal hostname and every host the splash page loads assets from. It must also include the domains of any social or single sign-on identity provider you offer. If you add a login option, read how to enable single sign-on and add that provider's domains. One missing asset host produces the half-drawn page.

The opposite mistake also causes trouble. Devices test connectivity by checking a predefined domain name, according to Purple's support article. If that probe domain sits in the walled garden, the device believes it is online. The prompt never appears and the guest is left stranded.

Northbound portal interface credentials

On SmartZone, the northbound portal interface is how an external portal tells the controller a guest has logged in. The portal authenticates to that interface with a password set on the controller. If that password changes on one side only, the portal cannot authorise anyone. The guest completes the form and loops back to the splash page.

RADIUS authentication and accounting

The controller forwards the one-time login to RADIUS. Authentication fails if the shared secret differs, the RADIUS server is unreachable, or requests arrive from an address the server does not recognise. Accounting failures are quieter. Guests get online, but session start and stop records never arrive.

HTTPS redirect behaviour

Modern browsers expect a login page over HTTPS. Purple's Cisco WLC certificate article describes the effect on Cisco controllers. An HTTP redirect to a controller address triggers a security warning, and the guest must click through. The fix there is a publicly trusted certificate whose Common Name matches the controller's web authentication hostname. The same principle applies when you enable HTTPS redirect on a Ruckus controller. An expired certificate, or a name mismatch, brings the warning back.

How do you work out which cause you have?

Start from the symptom, not the configuration. The table maps each symptom to its most likely cause and to the first place you should look.

Symptom	Most likely cause	Where to look first	First check
No login prompt, browser times out	Hotspot logon URL wrong, or wrong hotspot service on the WLAN	Hotspot (WISPr) service and WLAN settings	Open neverssl.com on a test device and see where it lands
Splash page loads without images or buttons	Asset or identity provider host missing from walled garden	Walled garden list	Load the portal on a laptop and list every blocked host in browser developer tools
Device says online, no prompt, no internet	Connectivity probe domain in walled garden	Walled garden list	Remove broad wildcard entries and retest
Certificate warning before portal	HTTPS redirect without a trusted, matching certificate	Controller certificate settings	Compare certificate name and expiry date with the redirect hostname
Form completes, guest loops back	Northbound portal interface password mismatch	Northbound interface settings and portal integration	Confirm the password matches on both sides
Login rejected after form	RADIUS shared secret or source address mismatch	RADIUS authentication service and client events	Look for authentication timeouts or rejects
Guests online, no session data	RADIUS accounting misconfigured or not attached	RADIUS accounting service on the WLAN	Confirm accounting is enabled and pointed at the right server

Reproduce it on a clean device

Forget the SSID on a test phone and a test laptop, then reconnect. If the prompt does not open, Purple's support article recommends browsing to neverssl.com. That site avoids SSL redirect problems, so it shows whether the redirect itself works.

Read the client's events

Every Ruckus platform keeps a client event history. On SmartZone, use the event and alarm logs and the client's connection history. On Ruckus One, open the client and review its events. On Unleashed, check the event log for the client's MAC address. Look for three things: whether the client associated, whether it was redirected, and whether RADIUS accepted or rejected it. That sequence tells you which link in the chain broke.

How do you fix it on SmartZone, Ruckus One and Unleashed?

The fixes follow the same order on all three platforms. The menus differ, so follow the Ruckus documentation for your release and the Captive Portal support article for Purple's values.

SmartZone

Confirm that the WLAN uses the hotspot (WISPr) service you expect, and that its logon URL matches the integration. Rebuild the walled garden from the current list, not from memory. Check that the northbound portal interface password matches the one configured for the portal. Then confirm the RADIUS authentication and accounting services both point to the right servers with the right shared secret.

Ruckus One

Ruckus One manages the same WISPr elements centrally. Check the guest network's portal provider settings, walled garden and RADIUS services. Venue-level overrides deserve attention, because one venue can drift from the template applied everywhere else.

Unleashed

Unleashed runs the controller function on an access point, so check the hotspot service on that master AP. Pay attention to the walled garden and RADIUS settings, and confirm the hotspot service is attached to the guest WLAN.

Rule out look-alike faults

Some complaints look like portal faults but are not. If guests are prompted again as they walk between access points, read resolving roaming issues in corporate WLANs. If sessions drop at random on 5GHz channels, the DFS radar event diagnostics checklist is the better starting point.

What does this look like in a live venue?

The two scenarios below are illustrative. They show the method rather than reporting a named deployment.

Scenario 1: a 200-room hotel after a splash page redesign

Situation. The marketing team relaunched the hotel's splash page. The next morning, the front desk reported that guests saw a blank page with a single form field.

What was done. The engineer loaded the portal on a laptop and listed the blocked requests in the browser's developer tools. The new design pulled fonts and images from a host that was missing from the SmartZone walled garden. The engineer added that host, reconnected a test phone and a test laptop, and confirmed both rendered the full page.

Outcome. The full splash page rendered on both test devices on the first retest. The fix was one walled garden entry, and the client events showed guests passing redirect and RADIUS acceptance again. For more on guest experience in this vertical, see Purple for Hotels.

Scenario 2: a 40-store retail chain after a controller migration

Situation. A retailer moved its stores to a new SmartZone cluster. Shoppers could still get online, but guest reporting showed zero new sessions across all 40 stores.

What was done. The client events showed RADIUS authentication accepts but no accounting records. The accounting service had not been attached to the guest WLAN on the new cluster. The engineer attached it and confirmed the shared secret matched.

Outcome. Session records reappeared from all 40 stores. Shoppers saw no disruption, because only reporting had been affected. See Purple for Retail for how that session data feeds shopper insight.

How do you stop Ruckus captive portal faults happening again?

Most repeat faults come from change, not from failure. Five habits prevent them:

1. Treat the walled garden as a controlled document. Record every entry, its owner and the reason it exists. Review it whenever the splash page changes.
2. Rotate secrets on both sides together. Change the northbound portal interface password and the RADIUS shared secret in a single change window, never one side alone.
3. Track certificate expiry. Diarise renewal well before the HTTPS redirect certificate expires, and recheck the name match afterwards.
4. Test after every change. Run the same check on an iPhone, an Android phone, a Windows laptop and a macOS laptop. Different operating systems handle the Captive Network Assistant in different ways.
5. Watch session counts daily. A sudden drop to zero in your WiFi analytics points to accounting before any guest complains.

Keep the guest network open, as Purple's support article recommends. An open network is the standard convention, and familiar behaviour reduces friction at login. For transport operators, where passengers connect on the move, the same checks apply; see Purple for Trains.

Frequently asked questions

Does Purple work with Ruckus SmartZone, Ruckus One and Unleashed?

Yes, Purple Guest WiFi runs on Ruckus hotspot (WISPr) services as an external captive portal. Purple is hardware-agnostic and also works with Cisco Meraki, HPE Aruba, Juniper Mist, Ubiquiti UniFi, Cambium, Extreme and Fortinet. The controller handles redirect and RADIUS, while Purple hosts the splash page and authenticates the guest. Configuration values and steps are in Purple's Captive Portal support article.

Do we need new access points to add Purple to an existing Ruckus network?

No, Purple runs as a cloud overlay on the Ruckus access points and controller you already own. You configure a hotspot service, walled garden and RADIUS settings on the controller, then point the guest WLAN at Purple. Nothing is replaced on site. Most of the effort sits in testing the redirect across iOS, Android, Windows and macOS devices before you go live.

Can we move from the built-in Ruckus guest portal to Purple without disrupting guests?

Yes, if you build the Purple configuration on a separate test WLAN first. Set up the hotspot service, walled garden and RADIUS services alongside your live guest network, and prove the full login on test devices. Once it works, attach the new hotspot service to the live WLAN in a quiet period. Guests see a new splash page, not an outage.

How does Purple handle guest data collected through a Ruckus captive portal?

Purple collects first-party data through conscious-choice opt-ins on the splash page. Purple is certified to ISO 27001 and Cyber Essentials, and operates in line with GDPR and CCPA. The Ruckus controller holds no marketing data. It passes a one-time login to Purple's RADIUS server, so guest details stay within Purple's certified platform rather than spreading across individual site controllers.

How long does a Ruckus captive portal deployment with Purple take?

A single site is usually configured within one working session, because no hardware changes. The controller needs a hotspot service, a walled garden and RADIUS authentication and accounting. Multi-site estates take longer, mainly for testing and change control rather than configuration. On Ruckus One or SmartZone, a template applied centrally keeps every venue consistent and reduces the risk of drift between sites.

What scale is Purple's guest WiFi platform proven at?

Purple runs across 80,000+ live venues and recorded 440 million logins in 2024, according to Purple's own company data. Those venues span hospitality, retail, transport, education and the public sector. Purple has operated since 2012, and every deployment uses the same splash page and RADIUS flow described in this guide, whichever supported hardware vendor runs the network underneath.