Portal loads but the WiFi never unlocks
This is the most common failure in an external portal, and it is never the portal page. The page did its job. The step that failed is the call from VoqadoWiFi back to your controller asking it to let the device online.
Causes, in the order to check them
1. network or timeout: the controller cannot be reachedOmada and UniFi
The controller address saved in the dashboard is a LAN address, the wrong port, or behind carrier grade NAT. Each attempt waits 8 seconds before it gives up.
Open the controller address from a phone on mobile data, not on your venue network. If it does not load there, VoqadoWiFi cannot reach it either.
Give the controller a public HTTPS address: a tunnel, a forwarded port, or a controller on a VPS. On Omada OC200, OC300 and software controllers it must answer on port 443.
2. auth on Omada: the token was rejected and there is no fallbackOmada
The one time token expired (-1001), or the site or MAC did not match (-1003, -1005), and the location has no OpenAPI or operator credentials to try next. Portal Health shows “Token-based auth failed and no operator/API credentials configured”.
Look for the Omada error code on the failed attempt in Portal Health.
For -1001, shorten the form. For -1003 and -1005, check the portal URL has no query string of its own and the Site ID is right. See Omada error codes.
3. auth on UniFi: the controller rejected the loginUniFi
The stored account is a ui.com cloud account, has two factor on, or the password changed. Portal Health shows “login rejected (HTTP 400, 401 or 403)”.
Run Test Connection on the location. It reports the same rejection.
Create a local admin without two factor, save it on the location, and test again. More in UniFi 403.
4. controller: the controller answered with an errorUniFi
Most often api.err.NoSiteContext: the site saved in the dashboard does not exist on the controller, usually because the display name was used instead of the internal id.
Run Test Connection and compare the site list with what is saved.
Click the venue’s site in the Test Connection list to fill the exact id, and save.
5. ssl: a certificate problem on the way to the controllerOmada
The Omada token call checks the controller’s certificate, and a factory self signed certificate fails it. UniFi calls accept self signed certificates by default.
The failed attempt shows ssl, or auth right after a token attempt on a self hosted controller.
Put a trusted certificate in front of the controller, for example with a reverse proxy or a tunnel that terminates HTTPS.
6. Omada: a query string pasted into the portal URLOmada
Omada appends clientMac, apMac, ssidName, radioId and token. A second question mark mangles them, so the portal has nothing valid to authorize.
Read the portal URL in the controller. It should end in your venue slug, with nothing after it.
Paste https://www.voqadowifi.com/portal/your-venue-slug exactly as the dashboard prints it.
Reference
| Error kind | What it means | Where to look |
|---|---|---|
| network | The controller address could not be reached | Address, port, tunnel |
| timeout | No answer within 8 seconds | Reachability, carrier grade NAT |
| ssl | Certificate or TLS failure | Certificate on the controller |
| auth | Login or token rejected, or nothing configured to try | Account, token, Controller ID |
| controller | The controller answered with an error | Site id, Site ID, error code |
| unknown | Anything else | The error message on the attempt |
Questions
What does the guest see when this happens?
Where is Portal Health?
It works for me but not for guests. Why?
Keep reading
Error kinds and codes on this page are the ones the VoqadoWiFi integration records, checked against the code on 7 October 2026.
See every authorization attempt
Portal Health in the free dashboard shows each guest login with its error kind and code. One location and 25 guest logins a month, no card.