Troubleshooting

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

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.
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.

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.	Increase CACHE_SERVER_EAP_SESSION_SEC if the client/network is slow to respond between EAP rounds; otherwise this is expected for an abandoned or very delayed exchange.
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 - increase CACHE_SERVER_EAP_SESSION_SEC if this happens on a consistently slow network.

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.