NetScaler Console service

Troubleshoot issues using the diagnostic tool or the NetScaler Console GUI


The diagnostic tool is applicable only for the NetScaler instances onboarded or to be onboarded using the Console Advisory Connect based low-touch onboarding.

For more information, see Low-touch onboarding of NetScaler instances using NetScaler Console connect.

When you onboard a NetScaler instance onto NetScaler Console, you might experience a few issues that prevent the NetScaler instance from successfully onboarding. As an administrator, you must know the reason for the onboarding failure. You can perform diagnostic checks using the diagnostic tool when you:

  • Experience any issues during auto-onboarding or script-based onboarding

  • Want to ensure if the NetScaler instance is ready to onboard

  • Want to analyze issues for the already onboarded NetScaler instances that show “Down” status in the NetScaler Console GUI

If Console Advisory Connect is enabled on the NetScaler instance, the diagnostic details are automatically sent to Citrix and you can view details in the NetScaler Console GUI. If Console Advisory Connect is not enabled, you can manually use the diagnostic tool.

Manually use the diagnostic tool

The diagnostic tool is available as part of the mastools upgrade (13.1-2.x or later) and accessible at /var/mastools/scripts. You can verify the mastools version by running the cat /var/mastools/version.txt command in the NetScaler instance.

To run the diagnostic tool:

  1. Using an SSH client, log on to the NetScaler instance.

  2. Type shell and press Enter to switch to bash mode.

  3. Type cd /var/mastools/scripts.

  4. Type sh mastools_diag.

The tool starts and displays the results for the following diagnostic checks:

  • nscli

  • DNS configuration

  • Internet connection

  • Instance to ADM connection

  • User privilege

If the issues still persist even after troubleshooting, you can contact support. When you contact support, you must provide the configuration information that is displayed after you run the diagnostic tool.

The following is an example of diagnostic results for an NetScaler instance that has no issues:

Diagnostic results for no issues NetScaler instance

  • 1 – Displays the type of diagnostic check

  • 2 – Displays the diagnostic check results either in green or in red. Green indicates the result is successful and red indicates the result is not successful.

  • 3 – Displays the NetScaler Console configuration information in yellow each time you run the diagnostic tool. If you want to contact NetScaler support, you must provide this information.

Validate the NetScaler instance readiness for onboarding using the diagnostic tool

Before you onboard the NetScaler instance to NetScaler Console, you can check the readiness of the NetScaler instance, by running the diagnostic tool on the NetScaler instance. If the NetScaler instance has no issues and ready to onboard, the tool displays the device not claimed on ADM message.

Device not claimed on NetScaler Console

View NetScaler diagnostic information in NetScaler Console GUI

Navigate to Infrastructure > Instances > NetScaler and click Asset Inventory to see the newly added Onboarding Readiness option that provides the NetScaler instance onboarding readiness status such as Needs Review or OK.

  • Needs Review. The NetScaler instance has issues that need to be fixed.

  • OK. The NetScaler instance is ready to onboard.


If the Onboarding Readiness appears blank, it means the NetScaler instance is not running with the latest image that has diagnostic support.

If the NetScaler instance has any issues, the Needs Review option appears, and you can click to view more details.

Auto diagnostic message

After you click Needs Review, the NetScaler Diagnostics Details page displays the issue details.

Auto diagnostic issue details

  • Category. Provides the issue category.

  • Status. Provides the issue status such as Needs Review, OK, or Not Applicable.

  • Recommendation. Provides the required recommendation to troubleshoot the issue.

After you fix the issue, the status in the Onboarding Readiness gets changed to OK.


The following are some of the NetScaler instance issues and their troubleshooting steps:

Invalid user name or password

Invalid credentials

Workaround: Ensure the user name and password provided in the Admin profile are correct. If you have modified the NetScaler instance password, you must modify the admin profiles of the instances. For more information, see Modify the admin profile.

DNS configuration error

DNS configuration error

Workaround: Ensure the DNS is configured or the DNS IP address is valid. For more information, see DNS configuration.

No internet connection

Workaround: Ensure that the firewall setting is not blocking the internet access and the required proxy is configured.

No connection to NetScaler Console endpoint

Workaround: Ensure to check firewall settings and the following NetScaler Console endpoints are not blocked in the firewall:





If no issue found in the diagnostic checks and the no connection issue still persists, make a note of the NetScaler Console configuration information (available in yellow) and contact NetScaler support.

When you perform a test run to ensure that the NetScaler instance is ready to onboard, the following issues maybe seen:

Built-in agent dry run timeout

If the results of the dry run are not fetched within 5 minutes, a Timeout message appears.


Recommendation: It is recommended that you verify whether the NetScaler instance is running with the latest image that has diagnostic support. Also, in the Asset Selection table, the Onboarding Readiness column appears blank.

Red outline on the device profile dropdown

NetScaler authentication fails during the dry run and a red outline appears on the device profile dropdown.

Profile Error

Recommendation: Re-enter the NetScaler user admin credentials again, create the device profile and click Test to run the dry run again.

Troubleshoot issues using the diagnostic tool or the NetScaler Console GUI