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 on the NAS & AAA Servers page. Ensure the shared secret is also configured correctly. If this keeps happening intermittently for the same NAS, its IP is probably not static (for example 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 (for example 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 on the Tenants & NAIs page (MSP accounts), 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 on the NAS & AAA Servers page.
ERR11: Access from this NAS is restricted	The NAS is blocked. The Status column on the NAS & AAA Servers page shows a Blocked badge with the reason.	If the badge says Blocked: over plan, the account has gone over its plan limits. Upgrading the plan lifts the block right away. For any other reason, contact SpherAAA support.
ERR06: Invalid Message-Authenticator, check shared secret, ERR06: Invalid Secret. (PAP) or ERR06: Invalid Request Authenticator (accounting)	The shared secret on the NAS/AP/controller doesn't match the one configured for that NAS in SpherAAA. The request is listed under Discarded Requests, and the NAS usually gets no reply, so it looks like a timeout.	Confirm the shared secret matches exactly (no extra whitespace) on both the NAS device and the NAS & AAA Servers page in SpherAAA.
Message-Authenticator AVP is required.	The NAS sent an EAP request, or its entry requires Message-Authenticator, without that attribute.	Enable Message-Authenticator on the NAS device. For EAP it's always required.

RadSec Errors

These show up on the Discarded Requests page.

Error	Description	Resolution
RadSec client certificate rejected from <ip>: certificate not registered	The RadSec client at <ip> presented a certificate SpherAAA doesn't recognise. Common causes: the client uses a certificate from your own CA, and either the CA hasn't been imported or the certificate hasn't been registered under it. 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 register the client's certificate under it. 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 expired or not yet valid	The client certificate has expired, or its start date is still in the future (for example, the clock was wrong on the system that issued it).	Renew or re-issue the client certificate, then install it on the client, or register it if it comes from your own CA. See Renewing a certificate.
RadSec client certificate rejected: issuing CA no longer imported	The CA this certificate was registered under has been deleted.	Re-import the CA under Alternative CA Certificates, or register the certificate under the correct CA again.
RadSec client certificate rejected: issuing CA expired	The imported CA certificate itself has expired.	Import the CA's renewed certificate, and register the client certificates it issued under it.
RadSec client certificate rejected: certificate registered by more than one tenant	The same client certificate is registered in two SpherAAA accounts.	Register each client certificate in one account only. If the other registration isn't in an account you manage, contact SpherAAA support.
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	The certificate is registered, but the CA it's registered under no longer matches the one that signed it, for example because the CA was re-imported with a different key.	Import the CA certificate that actually signed the client's certificate under Alternative CA Certificates, then register the client certificate again.

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 after its full authentication) or doesn't exist (for example after a server restart, when the reconnect reaches a different SpherAAA server, or on 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 after the full authentication, 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.