Troubleshooting

Solutions to common errors when configuring and running SpherAAA, covering PolicyLogic, NAS configuration, authentication workflows, and RADIUS operations.

Where to look

Under Analytics in the dashboard:

• RADIUS Logs: every request and reply, with attributes (passwords masked), result and timing.
• Discarded Requests: requests SpherAAA dropped before running your policy, for example from an unknown NAS or with a RadSec certificate problem. For RadSec certificate errors, the certificate identity is partly masked: personal parts such as CN, email, UID and serial number show only their first 3 characters (for example CN=CNM***), while organisation fields (O, OU, C) stay readable. A bare serial number shows its first 4 characters. Certificate names inside error messages are masked the same way.
• System Logs: errors, including PolicyLogic script errors.
• User Logs: output from log() calls in your scripts.

PolicyLogic Errors

Error	Description	Resolution
JSInit - JS execution exception: ReferenceError: start is not defined	The required entry-point function start() is missing from your PolicyLogic script. SpherAAA invokes this function to begin processing authentication or accounting requests.	Define the start() function as the entry point in your PolicyLogic. Example: function start() { // Your authentication logic here your_function(); }
Reply-Message: "PolicyLogic error. Check platform logs"	An uncaught exception occurred while your PolicyLogic script was running - a syntax error, a call to an undefined function, or an unhandled error from a Collection.*/Vault.*/EAP call.	Check the platform logs around the time of the request for the underlying JavaScript exception and stack trace, then fix the offending line in PolicyLogic.

RADIUS / NAS Errors

Error	Description	Resolution
ERR01: Unrecognized NAS client IP: <src_ip>	The RADIUS client IP address <src_ip> is not registered in the tenant's NAS configuration. SpherAAA rejects requests from unrecognized sources for security.	Add the IP address <src_ip> to your tenant's NAS configuration under Configuration > NAS. Ensure the shared secret is also configured correctly. If this keeps happening intermittently for the same NAS, its IP is probably not static (e.g. a dynamic/DHCP-assigned address) - see Dynamic or changing NAS IP addresses and switch that entry to RADSEC instead, which identifies the client by certificate rather than source IP.
ERR02: Bad user identity <username> from MSO-NAS	For an MSP/MSO NAS using NAI-based routing, the incoming User-Name doesn't match the configured routing pattern (nai_regex) for that NAS.	Confirm the client's identity is in the expected NAI format (e.g. user@realm) and that the NAS's nai_regex/routing configuration matches it.
ERR03: Undefined NAI <realm>	The realm portion of the user's identity doesn't match any configured provider realm, so SpherAAA can't route the request to a provider.	Add the realm to a provider's configuration under Configuration > Realms, or correct the realm the client is sending.
ERR10: Routing by User-Name is not ready for <username> from MSP-NAS	The MSP/MSO NAS has an nai_regex configured, but no matching nai_group routing rule exists for it yet.	Configure the NAI routing group (nai_group) for this NAS under Configuration > NAS.
ERR11: Access from this NAS is restricted	The NAS has been explicitly marked as restricted in its configuration.	Review the NAS's Restricted setting under Configuration > NAS and the accompanying reason; remove the restriction if access should be allowed.
Request silently ignored, or rejected with a Message-Authenticator related error	The shared secret configured on the NAS/AP/controller doesn't match the shared secret configured for that NAS in SpherAAA.	Confirm the shared secret matches exactly (no extra whitespace) on both the NAS device and Configuration > NAS in SpherAAA.

RadSec Errors

These show up on the Discarded Requests page.

Error	Description	Resolution
RadSec client certificate rejected from <ip>: certificate not registered (neither its serial number nor its issuer CA is in RadSec certificates)	The RadSec client at <ip> presented a certificate SpherAAA doesn't recognise. Common causes: the client uses a certificate from your own CA and that CA hasn't been imported; the device still has an old or default certificate configured instead of the one generated in SpherAAA; or the generated certificate was deleted.	If the client uses your own CA, import the CA that directly signed its certificate under Alternative CA Certificates, and add a NAS entry for the client's IP address (see that section). Otherwise, install the SpherAAA-generated RADSEC client certificate on the client, or generate a new one. Clients that are already connected need to reconnect.
RadSec client certificate rejected: certificate revoked	The client's SpherAAA-generated certificate has been revoked.	Generate a new RADSEC client certificate and install it on the client.
RadSec client certificate rejected: not signed by the registered issuer CA	A CA with the same name is imported, but it isn't the one that signed this certificate, for example a different CA or a CA that was re-issued with a new key.	Import the CA certificate that actually signed the client's certificate under Alternative CA Certificates.
TLS connection succeeds, but requests are rejected as an unrecognized client	The client was accepted through an imported CA, but there's no NAS entry for its IP address.	Add a NAS entry (Client (Host/IP)) for the client's IP address, with the environment it should use. See Alternative CA Certificates.

Session / State Errors

Error	Description	Resolution
EAP-Session for the current state is not found	The client's RADIUS State attribute doesn't match any in-progress EAP session - usually because too much time passed between rounds of the exchange and the session expired.	Expected for an abandoned or very delayed exchange. If it happens often, check the client and the network path for delays between EAP rounds.
TLS-Session for the current state is not found	Same as above, but for the TLS handshake state specifically - the client took too long between fragments/rounds of the TLS exchange.	Same as above. If it happens often, check the client and the network path for delays.

EAP-TLS / Certificate Errors

Error	Description	Resolution
Reply-Message: "Certificate not found"	The client's certificate wasn't found by checkTLSCert() - it was never issued by SpherAAA's PKI, or it has been deleted/replaced.	Confirm the device has a current, valid certificate issued by your EAP-TLS PKI, and reissue if needed.
user.X509.OCSP_Response: "revoked"	OCSP is enabled (ocsp_enabled = true) and the certificate authority reports this certificate as revoked.	Expected if the certificate was intentionally revoked. Reissue a new certificate to the device if access should be restored.
user.X509.OCSP_Response: "error"	SpherAAA couldn't reach the OCSP responder to check certificate status.	Check connectivity from SpherAAA to the OCSP responder URL. PolicyLogic decides whether to treat this as a pass or fail - see OCSP Response.

Fast-Reauth

Error	Description	Resolution
A reconnecting device gets rejected even though it authenticated fine minutes earlier	PolicyLogic doesn't check radius.session['Fast-Reauth'], so a Fast-Reauth request - which has no Phase 2 data to check - falls through your normal credential checks and fails.	Add a verifyFastReauth() check to your verifyAuthTypes() chain, as shown in Fast-Reauth.
Devices never seem to use Fast-Reauth - every reconnect runs a full TLS handshake	Either fast_reauth isn't enabled on the relevant EapTLS/EapTTLS/EapPEAP instance, or the client's cached TLS session has expired (1 hour of inactivity) or doesn't exist (e.g. after a server restart, or the client's first connection).	Confirm fast_reauth = true; is set in PolicyLogic. If it is, reconnect the same device again soon after its first successful authentication to confirm Fast-Reauth engages - a gap longer than an hour, or a device connecting for the first time, will always do a full authentication.
Session resumed but no cached identity - please reauthenticate (or your own custom reply for this case)	The client's TLS session resumed successfully, but the earlier full authentication that created it never actually reached Access-Accept (for example, it failed Phase 2 or was rejected by policy).	Expected, and self-healing - the client automatically retries with a full authentication. If it keeps happening for the same device, check why that device's full authentication is failing.
EAP-TLS Fast-Reauth device-eligibility check receives an unexpected identity (a long number instead of the outer username)	For EAP-TLS, SpherAAA caches the certificate's SerialNumber by default, not the outer EAP identity - see Fast-Reauth.	Key your eligibility check on SerialNumber instead, or override what gets cached with radius.session['Fast-Reauth-Identity'].

Authentication Errors

Error	Description	Resolution
Reply-Message: "User not found"	The default reply from verifyUserPassAuth()/verifyAuthTypes() when no verify* check in the chain returned true - most commonly a User-Name/Tunnel-User-Name that doesn't exist in your user store, or a password mismatch.	Confirm the user exists in the relevant collection and the password matches. If using EAP-TTLS/PEAP, check radius.request['Inner-Auth-Method'] to see which inner method the client actually used.
Reply-Message: "Invalid MSCHAPv2 password"	The MS-CHAPv2 NT-Response the client sent doesn't match what SpherAAA computed from the stored password for that user.	Confirm the stored password for the user is correct and up to date.