Product Documentation
ADC
14.1 - Current Release 13.1 13.0 12.1
View PDF

Troubleshooting issues related to the installation, upgrade, and downgrade processes

May 2, 2023
Contributed by: 
S

If the appliance does not work as expected after you complete the installation, upgrade, or downgrade process, the first thing to do is to check for the most common causes of the problem.

Resources for troubleshooting

For best results, use the following resources to troubleshoot an issue related to installing, upgrading, or downgrading a NetScaler:

  • The configuration files from the appliance. In case of a High Availability pair, the configuration files from both appliances.
  • The following files from the appliance(s):
    • The relevant newnslog files.
    • The ns.log file.
    • The messages file.
  • A network topology diagram.

Issues and resolutions

Following are the most common installation, upgrade, and downgrade issues, and tips for resolving them:

  1. Issue

    Upgrading a NetScaler MPX appliance fails due to hardware and software incompatibility.

    Resolution

    See the NetScaler MPX hardware-software compatibility matrix and check whether the software release is supported on the NetScaler MPX hardware.

  2. Issue

    Upgrading a NetScaler VPX appliance fails due to NetScaler VPX appliance and hypervisor incompatibility.

    Resolution

    See the NetScaler VPX appliance and hypervisor compatibility matrix and check whether the NetScaler VPX appliance model is supported on the hypervisor.

  3. Issue

    Upgrading a NetScaler appliance fails due to hardware errors.

    Resolution

    Validate the integrity of the NetScaler appliance. If you have a NetScaler hardware appliance, Citrix recommends running fsck for running a disk check and validating the integrity of the NetScaler hard drive.

    For more information, see How to Verify the File System Integrity of a NetScaler appliance.

  4. Issue

    Upgrading a NetScaler appliance by using the GUI stalls.

    Resolution

    Refresh the browser to check whether the upgrade is progressing or not.

  5. Issue

    Upgrading a NetScaler appliance fails due to low Space in /var Directory

    Resolution

    Free up space on the /var directory. For more information, see Refer to How to free space on /var directory.

  6. Issue

    The NetScaler is not accessible after the software downgrade

    Cause

    During the software downgrade process, if the configuration file of the existing release and build does not match the configuration file of the earlier release and build, the appliance cannot load the configuration, and the default IP address is assigned to the appliance.

    Resolution

    • Verify that the appliance is accessible from the console.
    • Verify the NSIP address and the routes on the appliance.
      • If the IP address has changed to the default 192.168.100.1 IP address, change the IP address as required.
      • Verify that the appliance is accessible.

  7. Issue

    During an upgrade, if I run the command for synchronizing, the following message appears:

    Command failed on the secondary node but succeeded on the primary node.

    Resolution

    Do not run any dependent commands (set /unset /bind /unbind) when High Availability (HA) synchronization is in progress.

  8. Issue

    During an upgrade process, traffic does not pass through the new primary node when you run the force failover command.

    Resolution

    • Check for problems with the network topology and the switch configurations.
    • Run the set L2param -garpreply ENABLED command to enable the GARP reply.
    • Try using virtual MAC if not already used.
    • Run the sendarp –a command from the primary node.

  9. Issue

    After upgrading or downgrading a NetScaler appliance, connecting to the appliance fails through SSH.

    Resolution

    Perform the following operations in the NetScaler appliance:

    • Remove old or insecure host keys at /nsconfig/ssh/ssh_host_*.
    • Review the custom SSHD configuration at /nsconfig/sshd_config and check if it is still relevant and compatible. Rename or remove the custom SSHD configuration accordingly.
    • Cold reboot the NetScaler appliance

  10. Issue

    In an HA pair, after you run the force HA failover command the devices keep rebooting. The secondary device does not come up after an upgrade.

    Resolution

    Check to see if the /var directory is full. If so, remove the old installation files. Run the df –h command to show the available disk space.

  11. Issue

    After upgrading an HA pair, one of the nodes is listed as state UNKNOWN.

    Resolution

    • Check to see if both nodes are running the same build. If the builds are not same and HA nodes have a version mismatch, some of the fields are shown as UNKNOWN when you run the show ha node command.
    • Check to see if the secondary appliance is reachable.

  12. Issue

    After you upgrade the NetScaler, the interface shows most of the load balancing virtual servers and services are DOWN.

    Resolution

    Verify that the SNIP address is active on the secondary appliance. Also, type the show service command to see if the service is running.

  13. Issue

    After performing an upgrade, all virtual servers are down on the secondary appliance.

    Resolution

    Enable the HA state and HA synchronization by running the following commands:

    • set node hastate enable
    • set node hasync enable

    Disabling HA is not recommended.

  14. Issue

    After performing a downgrade, the NetScaler does not boot up properly.

    Resolution

    Check to see if the correct license has been installed.

  15. Issue

    In an HA pair, some features do not get synchronized after an upgrade is performed.

    Resolution

    Run the sync ha file misc command to synchronize the configurations files from the primary node to secondary node.

  16. Issue

    During reboot, the following error message appears:

    One or more commands in ns.conf failedWhat should I do?

    Resolution

    Make sure that no command in the ns.conf file exceeds the 255 byte limit. In commands that create policies that are too long for the 255-byte limit, you can use pattern sets to shorten the policies.

    Example:

    add cs policy p11 -rule 'HTTP.REQ.URL.ENDSWITH_ANY("ctx_file_extensions")'
Done
<!--NeedCopy-->

    ctx_file_extensions is a default patset that covers a large number of extensions. In addition to the default pattern sets, you can create user-defined pattern sets. Add a patset by running the following command:

    add patset <name>
<!--NeedCopy-->

    Note: Patsets are supported only in release 9.3 or later.

  17. Issue

    When upgrading a NetScaler VPX appliance, I am told to free up space in /var. What files do I remove?

    Resolution

    Remove the old installation files from /var/tmp/ directory. Also remove unwanted files from /flash.

  18. Issue

    There is no connectivity to the graphical user interface (GUI) when you run the force HA failover command on the secondary appliance.

    Resolution

    Log on to the secondary appliance using the command line interface and enable the access to GUI by running the set ns ip <IP> -gui enabled command.

  19. Issue

    After performing an upgrade, and when I click on any link on the GUI that has to load a java applet (Upgrade Wizard or license Wizard), the following error message appears: GUI version does not match with the kernel version. Please close this instance, clear java plug-in cache and reopen.

    Resolution

    • Log on to the NetScaler using the GUI.
    • Navigate to NetScaler Gateway > Global Settings.
    • Click Change Global Settings under Settings.
    • In the details pane, under Client Experience, select Default from the UI theme list.
    • Click OK.

  20. Issue

    If upgrading a NetScaler appliance failed because of any reason, how to restore the appliance using the backed-up files?

    Resolution

    If the upgrade is unsuccessful then restore the appliance to the previous version of the NetScaler appliance using the backed-up files. For more information, see Backup and restore a NetScaler appliance.

    For more information on backup and restore of a NetScaler cluster setup, see Backup and restore of a cluster setup.

  21. Issue

    If licenses are missing after a failed upgrade of a NetScaler appliance, how to resolve the issue?

    Resolution

    If any license goes missing or if you want to reallocate the licenses, refer to the following topic Licensing overview.

Note

These troubleshooting steps also apply to issues with configuration loss when downgrading the software across multiple releases.

For any other issue, see the release notes, Knowledge Center articles, and FAQs.

Troubleshooting issues related to the installation, upgrade, and downgrade processes
May 2, 2023
Contributed by: 
S
May 2, 2023
Contributed by: 
S

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.