Troubleshooting agent upgrade from the Web UI

You can troubleshoot errors that occur upgrading agents from the Web UI by performing a few checks.

As part of the upgrade process, the Deploy server downloads and extracts the air-agentupgrade.jar file to a certain location to perform the agent upgrade. The handling of this file—specifically how it is copied and executed—varies depending on your Deploy version. To understand about the directory structure of a compact agent and non-compact agent, see Compact agent changes: Summary.
Note: Your system administrator must monitor the AGENT_HOME directory structure during a WebUI upgrade to track the creation, modification and deletion of files and directories.

To resolve errors, perform the following checks:

  • Verify that the air-agentupgrade.jar file is downloaded from the <serverInstallDir>/opt/ directory to the <agentInstallDir>/bin/ or <agentInstallDir>/var/upgrade/ directory.
    In version 7.2.x and earlier, the air-agentupgrade.jar file is downloaded to the <agentInstallDir>/bin/ directory. Starting with 7.3.x and later versions, the air-agentupgrade.jar file is downloaded to the <agentInstallDir>/var/upgrade/ directory.
    Note: If the air-agentupgrade.jar file is missing, you must verify that it exists on the <serverInstallDir>/opt/ directory. If the file exists, you must check for network connectivity issues or write permission errors on the agent.
  • Verify that the agent unzipped the air-agentupgrade.jar file into a specific sub-directory if the air-agentupgrade.jar file is present in the download path.

    The following table lists the download and unzipped locations of the air-agentupgrade.jar file for each version of Deploy:

    Version Download location Unzipped location
    7.2.x and earlier <agentInstallDir>/bin/ <agentInstallDir>/bin/agent-upgrade/
    7.3.x and later <agentInstallDir>/var/upgrade/ <agentInstallDir>/var/upgrade/unpack/
    If the air-agentupgrade.jar file is not created and unzipped in the specified location, then you must check for user permission issues.
    Note: If you use Security-Enhanced Linux (SELinux), it might block the agent user from creating directories. To resolve this issue, you must temporarily set SE-Linux to permissive mode.
  • Refer to the logs for specific error codes if the upgrade fails or stalls for any other reasons.

    In version 7.2.x and earlier, you must check the <agentInstallDir>/bin/upgrade.out log file. In version 7.3.x and later, you must check the <agentInstallDir>/var/log/upgrade.log file. You can view or download the upgrade log directly from the Log tab of the agent in the Web UI.

    If the log exists, you must review it for the Permission Denied or File Not Found errors.