ADC

Troubleshoot authentication, authorization and auditing issues

September 8, 2026

Contributed by:

C S

Troubleshoot authentication issues in NetScaler and NetScaler Gateway with aaad.debug module

Authentication in NetScaler Gateway is handled by the Authentication, authorization, and auditing (AAA) daemon. The raw authentication events that AAA daemon processes can be monitored by viewing the output of the aaad.debug module and serves as a valuable troubleshooting tool. The aaad.debug is a pipe as opposed to a flat file and does not display the results or log them. Therefore, the cat command can be used to view the output of aaad.debug. The process of using nsaaad.debug to troubleshoot an authentication problem is typically referred to as “debugging aaad”.

Debug process using aaad.debug module

This process is useful for troubleshooting authentication issues such as:

General authentication errors
Username/password failures
Authentication policy configuration errors
Group extraction discrepancies

Note: This process applies to NetScaler Gateway and NetScaler appliance.

Troubleshooting authentication issues

To troubleshoot authentication with aaad.debug module, complete the following procedure:

Connect to the NetScaler Gateway command line interface with a Secure Shell (SSH) client such as PuTTY.
Run the following command to switch to the shell prompt: shell
Run the following command to change to the /tmp directory: cd /tmp
Run the following command to start the debugging process: cat aaad.debug
Perform the authentication process that requires troubleshooting, such as a user logon attempt.
Monitor the output of the cat aaad.debug command to interpret and troubleshoot the authentication process.
Stop the debugging process by pressing Ctrl+Z.
Run the following command to record the output of aaad.debug to a file: cat aaad.debug | tee /var/tmp/<debuglogname>, where /var/tmp is the required directory path and <debuglogname.log> is the required log name.

The following section provides examples of how aaad.debug module can be used to troubleshoot and interpret an authentication error.

Incorrect password

In the following example, the user enters an incorrect RADIUS password.

process_radius Got RADIUS event
process_radius Received BAD_ACCESS_REJECT for: <username>
process_radius Sending reject.
send_reject_with_code Rejecting with error code 4001
<!--NeedCopy-->

Invalid username

In the following example, the user enters an incorrect LDAP username.

/home/build/rs_121/usr.src/netscaler/aaad/ldap_drv.c[450]: receive_ldap_user_search_event 1-140: Admin authentication(Bind) succeeded, now attempting to search the user testusernew

/home/build/rs_121/usr.src/netscaler/aaad/ldap_drv.c[453]: receive_ldap_user_search_event 1-140: Number of entires in LDAP server response = 0

/home/build/rs_121/usr.src/netscaler/aaad/ldap_drv.c[459]: receive_ldap_user_search_event 1-140: ldap_first_entry returned null, user testusernew not found

/home/build/rs_121/usr.src/netscaler/aaad/naaad.c[4781]: send_reject_with_code 1-140: Not trying cascade again 4009

/home/build/rs_121/usr.src/netscaler/aaad/naaad.c[4783]: send_reject_with_code 1-140: sending reject to kernel for : testusernew

/home/build/rs_121/usr.src/netscaler/aaad/naaad.c[4801]: send_reject_with_code 1-140: Rejecting with error code 4009
<!--NeedCopy-->

Determining group extraction results

In the following example, the group extraction results can be determined. Many issues with AAA group access involve the user not picking up the correct session policies for their assigned group in a NetScaler Gateway appliance. Some common reasons for this include an incorrect spelling of AD or the Radius group name in the appliance and users not being a member of the security group in AD or the Radius server.

/usr/home/build/rs_80_48/usr.src/usr.bin/nsaaad/../../netscaler/aaad/ldap_drv.c[40]:
start_ldap_auth attempting to auth scottli @ 10.12.33.216

/usr/home/build/rs_80_48/usr.src/usr.bin/nsaaad/../../netscaler/aaad/ldap_drv.c[291]:

/usr/home/build/rs_80_48/usr.src/usr.bin/nsaaad/../../netscaler/aaad/ldap_drv.c[551]: recieve_ldap_user_search_event built group string for scottli of:Domain Admins
<!--NeedCopy-->

aaad.debug module error codes

The following table lists the various aaad.debug module error codes, cause for the error, and the resolution.

aaad.debug module error codes	Error message	Cause of error	Resolution
4001	Incorrect credentials/Password. Try again.	Incorrect credentials are supplied	Enter the correct credentials
4002	Not Permitted	This is a catch all error. Occurs when ldapbind operation fails for reasons other than incorrect user credentials.	Make sure bind operation is permitted
4003	Cannot connect to server. Try connecting again in a few minutes.	Server times out	Increase the LDAP/Radius server timeout value on NetScaler (Authentication > LDAP/Radius > Server > Timeout value). Default timeout value is 3 secs.
4004	System Error	NetScaler/NetScaler Gateway internal error or a runtime error in the appliance library	Check for the cause of the system error and reslove the same
4005	Socket Error	Socket error while talking to the authentication server	Make sure that LDAP/RADIUS server or any other authentication servers can listen on the ports mentioned in the authentication action configured on NetScaler. For example, a common error scenario can be that an ldapprofile on NetScaler is configured to use port 636 /SSL, however the same port is not open on the AD.
4006	Incorrect username	Bad (format) username passed to nsaaad, like empty username	Enter the correct username
4007	Incorrect password	Bad (format) password passed to nsaaad	Enter the correct password
4008	Passwords do not match	Password mismatch	Enter the correct password
4009	User not found	No such user	Login using a valid user present in AD
4010	You do not have permission to log on at this time	Restricted log on hours	Log on outside the restricted hours
4011	Your AD account is disabled	Account disabled	Get your AD account enabled
4012	Your password has expired	Password expired	Reset your password
4013	You do not have permission to log on	No dial-in permission (RADIUS specific). This usually happens if a user is not authorized to authenticate at a server.	Network access permission setting needs to be changed
4014	Could not change your password	Error in changing password. This can happen due to many reasons. One such reason could be trying to change the password using the non-ssl port provided in ldapprofile on NetScaler.	Ensure secure port and sec type is used for changing password
4015	Your account is temporarily locked	User AD account is locked	Get your AD account unlocked
4016	Could not update your password. The password must meet the length, complexity, and history requirements of the domain.	User password requirements not met while changing the password	Meet the needed requirements while changing the password
4017	NAC process	Microsoft Intune Specific. NetScaler Gateway is unable to verify device, either due to API failure or connectivity failure.	Ensure Microsoft Intune managed devices are reachable to NetScaler Gateway
4018	NAC Noncompliance	Microsoft Intune returns a status saying that this device is not compliant device	Ensure Microsoft Intune managed devices are compliant with NetScaler Gateway
4019	NAC Unmanaged	Microsoft Intune returns a status saying that this is not a managed device	Ensure Microsoft Intune specific configurations are in place
4020	Authentication not Supported	This error is seen in case of misconfiguration. For example, auth type is not supported by NetScaler or if the Authentciationprofile config is incorrect on NetScaler appliance or if accounting action (radius) is attempted for authentication.	Check the Authentication checkbox for the Authentication server on NetScaler if its unchecked. Use appropriate Authentication action on NetScaler.
4021	User Account Expired	The user account has expired	Get your user account renewed
4022	User account is locked by NetScaler	The user account is locked by NetScaler	Unlock the account using unlock aaa user <> command
4023	Max OTP Device limit reached	Device limit for receiving OTP reached	Either try unregistering the non-required OTP devices or continue with the ones already registered

Localize error messages generated by NetScaler nFactor system

This topic captures information on localizing error messages generated by NetScaler nFactor system. These messages include the extended authentication error strings that are obtained as part of enhanced authentication feedback.

The default error strings that are sent by nFactor subsystem are described in /var/netscaler/logon/LogonPoint/receiver/js/localization/en/ctxs.strings.js for English language. Error strings for other languages are found in corresponding directories in /var/netscaler/logon/LogonPoint/receiver/js/localization/.

You must create a portal theme based on RfWeb UI for localizing error messages.

At the command prompt, type:

add portaltheme custom_error_theme -basetheme RfWebUI

bind authentication vserver av1  -portaltheme custom_error_theme
<!--NeedCopy-->

After these commands are executed, a new directory is created in /var/netscaler/logon/themes/<name>. This directory contains a file named “strings.en.json.” This file is an empty json file to begin with. Administrator can add name-value pairs comprising of old and new error strings.

For example, { “No active policy during authentication”: “No active policy during authentication, Please contact administrator” }

In the preceding example, text on the left side is the existing error message that is sent by nFactor. The text on the right side is the replacement for that. Administrator can add more messages as required.

Enhanced authentication feedback

For obtaining extended error messages during authentication process, enhancedAuthenticationFeedback feature must be enabled.

At the command prompt, type:

set aaa parameter –enableEnhancedAuthFeedback YES
<!--NeedCopy-->

The official version of this product documentation is in English. Any non-English version is solely provided for your convenience and may include machine-translated content. For more information, please refer to the Machine Translation Disclaimer on Cloud Software Group home.

Was this helpful

NetScaler Secure Deployment Guide

Troubleshoot authentication, authorization and auditing issues

September 8, 2026

Contributed by:

C S

September 8, 2026

Contributed by:

C S

Troubleshoot authentication, authorization and auditing issues

Troubleshoot authentication issues in NetScaler and NetScaler Gateway with aaad.debug module

Troubleshooting authentication issues

Incorrect password

Invalid username

Determining group extraction results

aaad.debug module error codes

Localize error messages generated by NetScaler nFactor system

Enhanced authentication feedback

In this article