Troubleshooting
Key Takeaways
- The most common captive portal issue is a missing walled garden entry -- always verify and
107.178.250.42/32are in your controller's pre-auth access list.*.ironwifi.com - Authentication failures are typically caused by mismatched RADIUS shared secrets, incorrect ports, or disabled user accounts -- check the IronWiFi Console Reports > Authentication logs first.
- For 802.1X (WPA2/WPA3-Enterprise) issues, verify the EAP inner method matches on both client and server: use PAP for EAP-TTLS and MSCHAPv2 for PEAP.
- iOS and Android devices randomize MAC addresses by default, which breaks MAC-based authentication -- disable Private WiFi Address (iOS) or set Privacy to "Use device MAC" (Android).
- Use IronWiFi's Authentication Testing Tool to isolate whether the problem is in your IronWiFi configuration or your access point/controller setup.
Diagnose and resolve common IronWiFi issues with step-by-step solutions. Each section includes symptoms, causes, and fixes organized by category.
Quick Navigation
Authentication Issues: Access Rejected · Certificate Auth · MAC Auth · RADIUS Accounting · 802.1X Protocols
Captive Portal: Splash Page · Social Login · Stuck Users · Vouchers · Custom Pages · Browser Issues
Controllers: UniFi · Meraki · MikroTik
Network: Disconnections · Slow Auth · VLAN · Bandwidth · Mobile Devices
Integrations: Connector Sync · Webhooks · Email Delivery · API · Multi-Location
Diagnostic Tools: Auth Test · Request Logs · Packet Capture
Common Issues - Quick Fixes
Before diving into detailed troubleshooting, try these solutions for the most frequently reported issues:
| Problem | Quick Fix |
|---|---|
| Splash page won't load | Add |
| Users can't authenticate | Verify RADIUS server IP, customer authentication port, and shared secret match exactly |
| Authentication works but no internet | Check controller credentials and firewall allows port 8443 from |
| Social login fails | Add provider domains to walled garden: |
| iOS/Android won't connect | Disable Private WiFi Address (iOS) or set Privacy to "Use device MAC" (Android) |
| VLAN not assigned | Add |
Authentication Issues
Access Rejected
Symptoms: User cannot connect and receives a rejection message or error.
Common causes and solutions:
| Cause | How to fix |
|---|---|
| Invalid credentials | Go to Users in the IronWiFi Console and verify the username and password are correct |
| User disabled | Open the user's profile and confirm Status is set to "Enabled" |
| Time restrictions | Check the Login Time attribute in the user's profile to ensure the current time falls within allowed hours |
| Expired account | Review the Valid From and Valid To dates in the user's profile |
| Wrong authentication source | Verify the user's Authentication Source matches where their credentials are stored (local, Microsoft Entra ID, Google Workspace, etc.) |
Certificate Authentication Failure
Symptoms: EAP-TLS authentication fails with certificate-related errors.
Common causes and solutions:
| Cause | How to fix |
|---|---|
| Certificate expired | Check the certificate's validity dates and issue a new certificate if expired |
| Certificate revoked | In the IronWiFi Console, go to Certificates and verify the certificate is not in the revoked list |
| CA certificate not trusted | Install the IronWiFi CA certificate on the client device (download from Certificates > CA Certificate) |
| Wrong certificate selected | On the client device, open WiFi settings and select the correct user certificate for this network |
MAC Authentication Not Working
Symptoms: Device should authenticate automatically based on its MAC address but fails to connect.
Common causes and solutions:
| Cause | How to fix |
|---|---|
| MAC not in authorized list | Go to Users, open the user's profile, and add the device MAC address under Authorized Devices |
| MAC format mismatch | Use lowercase letters with colons as separators (e.g., |
| Feature not enabled | In your Captive Portal settings, enable MAC-based authentication |
| Authorization expired | Check if the MAC authorization has a time limit and re-authorize the device if needed |
RADIUS Accounting Issues
Symptoms: Session data not tracked, incorrect usage statistics, or accounting reports showing no data.
Common causes and solutions:
| Cause | How to fix |
|---|---|
| Accounting not enabled | In IronWiFi Console, go to Networks and verify RADIUS Accounting is enabled in your network settings |
| Wrong accounting port | Verify your controller is sending accounting packets to your customer accounting port (displayed in Network Settings). Check controller logs for accounting failures |
| Accounting-Start not received | Review Reports > Authentication to confirm Accounting-Start packets are arriving. If missing, check firewall rules for UDP traffic on your customer accounting port |
| Session timeout mismatched | Ensure Accounting-Interim-Interval on your controller matches or is lower than the Session-Timeout value in IronWiFi |
| Duplicate session IDs | Some controllers reuse session IDs. In IronWiFi Network settings, enable Unique Session ID to handle this |
| Data usage not accurate | Verify your controller sends Accounting-Update packets with Acct-Input-Octets and Acct-Output-Octets attributes |
802.1X Protocol Issues
Symptoms: Enterprise WiFi authentication fails with protocol-specific errors for EAP-TTLS or PEAP.
Common causes and solutions:
| Cause | How to fix |
|---|---|
| Inner authentication mismatch | For EAP-TTLS, verify inner method is set to PAP (not MSCHAPv2) on both client and server. For PEAP, use MSCHAPv2 |
| Server certificate not trusted | Client devices must trust the RADIUS server certificate. Install the IronWiFi CA certificate on client devices |
| Anonymous identity misconfigured | For privacy, use an anonymous outer identity (e.g., |
| Phase 2 authentication failing | Check user credentials are correct for the inner authentication method. Review Reports > Authentication for specific error messages |
| TLS version incompatibility | Ensure client devices support TLS 1.2 or higher. Older devices may need firmware updates |
| Domain name verification | If client enforces server name verification, ensure the certificate CN or SAN matches the RADIUS server domain |
Related Resources
- Use the Authentication Test tool to verify RADIUS configuration
- Check Request Logs for detailed error messages
- For mobile device issues, see Mobile Device Specific Issues
Captive Portal Issues
Splash Page Not Loading
Symptoms: Users see a white page, timeout error, or "page cannot be displayed" when connecting to WiFi.
Common causes and solutions:
| Cause | How to fix |
|---|---|
| Walled garden misconfigured | Add IronWiFi's IP address |
| Wrong redirect URL | Copy the Splash Page URL from your IronWiFi captive portal settings and paste it exactly into your controller's external portal URL field |
| DNS issues | Ensure your controller allows DNS traffic (port 53) before authentication. Add DNS servers to the pre-auth access list |
| HTTPS certificate problems | If using a custom domain, verify your SSL certificate is valid and properly installed |
Social Login Not Working
Symptoms: Users click a social login button (Google, Facebook, LinkedIn) but authentication fails or the login window doesn't appear.
Common causes and solutions:
| Cause | How to fix |
|---|---|
| Missing walled garden entries | Add the required domains to your controller's walled garden. For Google: |
| OAuth app misconfigured | In IronWiFi Console under Captive Portals > Authentication Providers, verify your OAuth Client ID and Secret are correct |
| Popup blocked | The user's browser may be blocking the login popup. They should allow popups for the splash page domain |
| Third-party cookies blocked | Social login requires third-party cookies. Users should enable cookies or try a different browser |
Users Stuck on Splash Page
Symptoms: Users complete authentication (see a success message) but cannot access the internet and may be redirected back to the splash page.
Common causes and solutions:
| Cause | How to fix |
|---|---|
| Controller not receiving auth response | For UniFi and similar controllers, verify the controller credentials in IronWiFi are correct and the controller is reachable from the internet (check firewall rules for port 8443) |
| Session not created | Go to Reports > Sessions in IronWiFi Console to check if a session was created. If not, review the authentication logs for errors |
| Client isolation enabled | If client isolation is enabled on your access points, it may block communication. Disable it or add exceptions for the captive portal |
| VLAN misconfiguration | Verify the post-auth VLAN assignment is correct and that the VLAN has internet access |
Voucher/Guest Pass Problems
Symptoms: Vouchers not working, guests cannot redeem codes, or voucher codes not generating.
Common causes and solutions:
| Cause | How to fix |
|---|---|
| Voucher expired | Check the Valid Until date in Captive Portals > Vouchers. Extend expiration or create new vouchers |
| Voucher already used | Each voucher code can typically be used once (unless configured otherwise). Verify usage count in the voucher details |
| Voucher not activated | Ensure the voucher status is set to Active in the IronWiFi Console |
| Wrong voucher format | Verify users are entering the code exactly as generated, including any dashes or special characters |
| Voucher page not accessible | Add voucher redemption domains to the walled garden. Ensure |
| Batch generation failed | When generating bulk vouchers, check browser console for errors. Try generating smaller batches (e.g., 100 at a time) |
| Email delivery failed | If vouchers should be emailed to guests, verify email settings in Account > Outgoing Emails |
Custom Splash Page Issues
Symptoms: Custom HTML/CSS not displaying correctly, JavaScript errors, or form submissions failing.
Common causes and solutions:
| Cause | How to fix |
|---|---|
| JavaScript errors | Open browser developer console (F12) and check the Console tab for errors. Fix syntax errors or missing dependencies |
| CSS not loading | Verify external CSS URLs are added to the walled garden. Use inline CSS or host assets on IronWiFi-friendly domains |
| Form fields not submitting | Ensure form field names match IronWiFi requirements (e.g., |
| Custom domain SSL issues | If using a custom domain, verify SSL certificate is valid and properly configured. Mixed content (HTTP on HTTPS page) will be blocked |
| External resources blocked | Add all third-party resources (fonts, images, scripts) to the walled garden or use data URIs for small assets |
| Mobile responsive issues | Test on actual mobile devices. Use CSS media queries and viewport meta tags for proper mobile rendering |
| Template variables not working | Verify you're using correct template syntax (e.g., |
Browser Compatibility Issues
Symptoms: Splash page works in some browsers but not others, or specific browser shows errors.
Common causes and solutions:
| Cause | How to fix |
|---|---|
| Captive portal detection disabled | iOS users: Ensure Auto-Join is enabled for the network. Android users: Enable Auto-connect in WiFi settings |
| Browser privacy mode blocking cookies | Social login and some authentication methods require cookies. Users should disable private/incognito mode or allow cookies |
| Safari blocking third-party cookies | For iOS/macOS Safari, users must enable Prevent Cross-Site Tracking exceptions or use a different browser |
| Popup blockers preventing social login | Users must allow popups for the splash page domain. Add exception in browser settings |
| Older browser versions | Recommend users update to latest browser version. Modern authentication protocols require updated browsers |
| Browser extensions interfering | Ad blockers or privacy extensions may block authentication. Users should disable extensions or whitelist the splash page |
| Redirect loops in Chrome | Clear browser cache and cookies. Verify the captive portal detection is working (disconnect and reconnect to WiFi) |
Related Resources
- Review Walled Garden configuration for complete setup
- For stuck users after auth, check Controller-Specific Issues
- Mobile device issues? See Mobile Device Specific Issues
Controller-Specific Issues
UniFi: Authorization Failed
Error:
unifi_authentication_failed
This error means IronWiFi cannot authenticate with your UniFi controller.
How to fix:
- In UniFi, create a dedicated local admin user (not SSO) with full admin privileges
- In IronWiFi Console, go to Captive Portals and update the UniFi controller credentials with this new user
- Test the connection by clicking Test Connection in the captive portal settings
Error:
unifi_gw_connection_failed
This error means IronWiFi cannot reach your UniFi controller over the network.
How to fix:
- Confirm your controller's public IP address or hostname is correct in IronWiFi
- Ensure your firewall allows inbound connections on port 8443 from IronWiFi's IP ()
107.178.250.42 - If your controller is behind NAT, set up port forwarding for port 8443 to your controller's internal IP
- If direct connection isn't possible, enable the Proxy feature in your IronWiFi captive portal settings
Meraki: RADIUS Timeout
Symptoms: Users experience long delays during authentication, or authentication times out completely.
How to fix:
- In Meraki Dashboard, go to Wireless > Access control and verify the RADIUS server IP matches IronWiFi's regional server (find this in your IronWiFi network settings)
- Confirm the RADIUS ports match your customer authentication and accounting ports (displayed in Network Settings)
- Double-check that the shared secret in Meraki exactly matches the one in IronWiFi (secrets are case-sensitive)
- Ensure your firewall allows outbound UDP traffic on your customer authentication and accounting ports to the IronWiFi RADIUS server
- If using RADIUS accounting, verify it's enabled in both Meraki and IronWiFi
MikroTik: Users Can't Authenticate
Symptoms: Users cannot authenticate through the MikroTik hotspot.
How to fix:
-
Verify your RADIUS configuration in the MikroTik terminal:
/radius printConfirm the server address, secret, and ports match your IronWiFi settings.
-
Check hotspot server settings:
/ip hotspot printEnsure the hotspot is enabled and assigned to the correct interface.
-
Verify walled garden entries include IronWiFi domains:
/ip hotspot walled-garden printAdd
and*.ironwifi.comif missing.107.178.250.42 -
Test with a local MikroTik user first to confirm the hotspot itself works, then switch to RADIUS authentication.
Network Issues
Intermittent Connectivity
Symptoms: Users experience random disconnections or need to re-authenticate frequently.
Common causes and solutions:
| Cause | How to fix |
|---|---|
| Session timeout too short | In IronWiFi Console, go to Networks > Attributes and increase the Session-Timeout value (e.g., 28800 for 8 hours) |
| Idle timeout too aggressive | Increase the Idle-Timeout attribute to allow longer periods of inactivity before disconnection |
| Network instability | Check your local network for issues such as interference, overloaded access points, or bandwidth problems |
| Roaming between APs | Enable seamless roaming (802.11r/k/v) on your access points and ensure all APs use the same SSID and security settings |
Slow Authentication
Symptoms: Authentication takes several seconds or longer than expected.
Common causes and solutions:
| Cause | How to fix |
|---|---|
| RADIUS server latency | Use the IronWiFi regional server closest to your location. Check your network settings for available regions |
| Controller to IronWiFi latency | If your controller has high latency to IronWiFi, enable the Proxy feature in your captive portal settings for a direct connection |
| DNS resolution delays | Configure reliable DNS servers (e.g., 8.8.8.8, 1.1.1.1) on your network and ensure DNS is allowed before authentication |
| Certificate chain issues | If using EAP-TLS, ensure your certificate chain is complete and doesn't require additional lookups during verification |
VLAN Assignment Issues
Symptoms: Users placed in wrong VLAN, dynamic VLAN not working, or network access incorrect after authentication.
Common causes and solutions:
| Cause | How to fix |
|---|---|
| VLAN attribute not configured | In IronWiFi Console, go to Users or Networks > Attributes and add the Tunnel-Private-Group-ID attribute with the VLAN ID |
| Controller not supporting dynamic VLAN | Verify your controller/AP supports 802.1X dynamic VLAN assignment. Check vendor documentation for RADIUS VLAN support |
| VLAN not created on switch | Ensure the VLAN ID exists on your network switches and has proper routing/internet access configured |
| Trunk port misconfiguration | Verify the port connecting your AP to the switch is configured as a trunk port allowing all required VLANs |
| VLAN override in controller | Some controllers have local VLAN settings that override RADIUS attributes. Check AP or SSID VLAN configuration |
| Multiple VLAN attributes conflicting | If using both Tunnel-Private-Group-ID and other VLAN attributes, ensure they match. Remove conflicting attributes |
| Guest VLAN fallback | Some controllers fall back to a guest VLAN on auth failure. Verify authentication is succeeding first |
Bandwidth Limits Not Working
Symptoms: User bandwidth exceeds configured limits, traffic shaping not applied, or speed restrictions ignored.
Common causes and solutions:
| Cause | How to fix |
|---|---|
| Rate limiting not configured | In IronWiFi Console, add WISPr-Bandwidth-Max-Down and WISPr-Bandwidth-Max-Up attributes to user profile or network (values in kbps) |
| Controller doesn't support rate limiting | Verify your controller supports WISPr bandwidth attributes. Not all vendors implement this feature |
| Per-user vs per-session limits | Some controllers apply limits per device, others per user. Test with single device to verify behavior |
| Burst settings too high | If your controller supports burst rates, lower the burst limit to enforce consistent speed limits |
| QoS conflicting with RADIUS | Controller QoS policies may override RADIUS attributes. Disable local QoS or set it to use RADIUS values |
| Cached sessions | After changing bandwidth limits, users may need to reconnect for new limits to apply. Force session termination in IronWiFi |
| Incorrect attribute format | Verify bandwidth values are in the correct unit (kbps, not Mbps). For 10 Mbps limit, use 10000 (kbps) |
Mobile Device Specific Issues
Symptoms: Certain mobile devices cannot connect while others work fine, or device-specific authentication errors.
Common causes and solutions:
| Cause | How to fix |
|---|---|
| iOS Private WiFi Address | iOS randomizes MAC addresses by default. Disable Private WiFi Address in iOS WiFi settings, or use user authentication instead of MAC auth |
| Android randomized MAC | Android 10+ randomizes MACs. In WiFi settings, set Privacy to Use device MAC for the network |
| iOS captive portal assistant closing | iOS may close the captive portal window too quickly. Ensure your success page shows for at least 2-3 seconds before redirect |
| Android not showing captive portal | Enable Auto-connect in Android WiFi settings. Ensure walled garden includes |
| iOS certificate trust issues | For 802.1X, install certificates via Apple Configurator or MDM. Manually installed certificates may not be trusted for WiFi |
| Android certificate installation | On Android, certificates must be installed as WiFi certificate not just VPN/App certificate |
| Device manufacturer customizations | Samsung, Xiaomi, and other manufacturers modify Android WiFi behavior. Test with stock Android device to isolate vendor-specific issues |
Related Resources
- For captive portal not showing, see Browser Compatibility Issues
- For 802.1X certificate issues, see 802.1X Protocol Issues
- Use Authentication Test to verify device connectivity
Integration Issues
Connector Sync Failing
Symptoms: Users from Google Workspace or Microsoft Entra ID are not appearing in IronWiFi, or changes are not being synchronized.
How to fix:
- Go to Connectors in IronWiFi Console and click Re-authorize to refresh the connection
- Verify the connector has the required API permissions in Google Admin Console or Azure Portal
- Check the Sync Logs in IronWiFi to identify specific errors
- Ensure your network allows outbound HTTPS connections to Google and Microsoft APIs
Webhook Not Received
Symptoms: Your application is not receiving webhook notifications from IronWiFi.
How to fix:
- Go to your Captive Portal settings in IronWiFi Console, find the Webhook URL field, and verify the URL is correct and includes
https:// - Confirm your receiving server is running and accessible from the internet
- Check your firewall allows inbound HTTPS connections from IronWiFi's IP ()
107.178.250.42 - Verify your server's SSL certificate is valid and not expired
Email/Notification Delivery Issues
Symptoms: Welcome emails, voucher codes, or password reset emails not received by users.
Common causes and solutions:
| Cause | How to fix |
|---|---|
| Email not configured | In IronWiFi Console, go to Account > Outgoing Emails and set up SMTP server or use IronWiFi email service |
| Wrong recipient email | Verify the user's email address is correct in their profile. Check for typos or extra spaces |
| Emails in spam folder | Ask users to check spam/junk folders. Add |
| SMTP authentication failed | Verify SMTP credentials (username, password, server, port) are correct. Test with an SMTP testing tool |
| Email rate limiting | Email providers may rate limit bulk emails. Reduce sending frequency or contact your email provider to increase limits |
| Template variables missing | If using custom email templates, ensure all required variables (e.g., |
| SPF/DKIM not configured | For custom domains, configure SPF and DKIM records in your DNS to improve deliverability and avoid spam filtering |
API Integration Issues
Symptoms: API calls failing, authentication errors, or unexpected responses from IronWiFi API.
Common causes and solutions:
| Cause | How to fix |
|---|---|
| Invalid API key | In IronWiFi Console, go to Account > API Keys and verify the key is active and not expired. Generate new key if needed |
| Wrong API endpoint | Verify you're using the correct regional API endpoint (e.g., |
| Rate limiting | IronWiFi API has rate limits. Implement exponential backoff and respect |
| Missing required parameters | Review API documentation for required fields. Check request body contains all mandatory parameters |
| Incorrect authentication header | Use |
| JSON parsing errors | Ensure request body is valid JSON. Use a JSON validator to check syntax before sending requests |
| CORS errors in browser | If calling API from browser, verify CORS is enabled for your domain in IronWiFi settings, or use server-side API calls instead |
Multi-Location Setup Issues
Symptoms: Users cannot roam between locations, authentication fails at secondary sites, or sessions not synchronized.
Common causes and solutions:
| Cause | How to fix |
|---|---|
| Different networks per location | Ensure all locations use the same Network in IronWiFi Console, or configure user access to multiple networks |
| RADIUS server region mismatch | For optimal performance, use regional RADIUS servers. Configure each location to use the nearest IronWiFi RADIUS server |
| User database not shared | Verify all locations are using the same authentication source (shared user database, not separate local users per location) |
| Session synchronization disabled | In multi-controller setups, enable session synchronization or use a unified controller with multiple sites |
| Firewall blocking inter-location traffic | If using site-to-site VPN, ensure firewall rules allow traffic between locations for seamless roaming |
| Different SSIDs per location | For transparent roaming, use the same SSID and security settings across all locations |
| Geolocation-based restrictions | Check if user or network settings have location-based restrictions that block access at certain sites |
Related Resources
- For connector setup, see Connector documentation
- Check Authentication Test to verify API integration
- Review Request Logs for webhook delivery status
Diagnostic Tools
Use these tools to diagnose issues before contacting support.
Authentication Test
Test RADIUS authentication without involving your controller:
- Go to ironwifi.com/authentication-testing-tool
- Enter your IronWiFi RADIUS server address and port
- Enter the shared secret from your network settings
- Select the authentication method (EAP-TTLS/PAP, PEAP-MSCHAPv2, PAP, or EAP-TLS)
- Enter test credentials (username and password)
- Click Test and review the response
A successful test confirms your IronWiFi configuration is correct. If this test passes but authentication fails from your controller, the issue is likely in your controller configuration.
Request Logs
View detailed authentication attempts in the IronWiFi Console:
- Navigate to Reports > Authentication
- Use filters to find specific requests by date, username, MAC address, or result (Accept/Reject)
- Click on any request to see the full RADIUS attributes sent and received
- Look for error messages or missing attributes that explain the failure
Packet Capture
For advanced debugging when other methods don't reveal the issue:
- On your controller or a network device, capture RADIUS traffic on your customer authentication and accounting ports (UDP)
- Look for Access-Request packets going to IronWiFi and Access-Accept or Access-Reject responses
- Verify that required attributes (User-Name, Called-Station-Id, etc.) are present in requests
- Compare the shared secret usage and attribute formats with IronWiFi documentation
Getting Help
Still experiencing issues? Follow these steps:
1. Check Service Status
Visit status.ironwifi.com first to verify no ongoing outages or maintenance.
2. Gather Diagnostic Information
Before contacting support, collect:
- Screenshots of error messages
- Request IDs from Request Logs
- Controller type and firmware version
- Steps to reproduce the issue
- Recent configuration changes
3. Contact Support
- Live chat: 24/7 at ironwifi.com
- Email: support@ironwifi.com
Include all diagnostic information for faster resolution.
Related Topics
- Solving Access-Reject Issues -- step-by-step guide for diagnosing rejected authentications
- Point of Failure Detection -- isolate whether the problem is client, AP, or RADIUS
- Network Configuration -- verify RADIUS server settings and shared secrets
- Service Monitor -- real-time monitoring of authentication activity
- Configuration Guides -- vendor-specific AP setup for RADIUS and captive portals
Was this page helpful?