Product Documentation

Troubleshooting

Aug 31, 2016

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 appliance:
  • 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.

Troubleshooting Issues Related to the Installation, Upgrade, and Downgrade Processes

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

    The NetScaler appliance 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.
  • Issue

    Configuration of the appliance is lost after you upgrade the software across multiple releases.

    Cause

    Some migration commands are built in for upgrading to the next release. Such commands might not be available across releases.

    Resolution
    • Verify the path of the upgrade process. Citrix recommends upgrading by one release at a time. For example, if the softer needs to be upgraded from NetScaler release 9.2 to NetScaler release 10.1, the following is the recommended path for the upgrade:
      • NetScaler release 9.2 to NetScaler release 9.3
      • NetScaler release 9.3 to NetScaler release 10
      • NetScaler release 10 to NetScaler release 10.1
    • Verify that the appliance has appropriate license files.
    • Verifying the configuration at each step of the upgrade process can give you pointers to the issue.
  • 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.

  • 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 VMAC if not already used.
    • Run the sendarp –a command from the primary node.
  • 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.

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

    After you upgrade the NetScaler appliance, 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.

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

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

    Resolution

    Check to see if the correct license has been installed.

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

  • 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
    
    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>
    
    Note: Patsets are supported only in release 9.3 or later.
  • 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.

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

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

메모

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.