ESA Upgrade Readiness Patch Error Messages and Resolutions

A list common errors found while applying the ESA readiness patch.

This article provides detailed information on error messages and their resolutions related to the ESA Upgrade Readiness Patch for version 10.2.0. It covers various issues such as insufficient disk space, version compatibility, unicast hosts file errors, analytics initialization, and service status checks. Each error message is accompanied by high-level steps for resolving the issue, ensuring a smooth upgrade process to ESA version 10.2.0.

Use the information provided in this section for the detailed steps to resolve the issues shown by the readiness patch.

Issue: Insufficient Disk Space

ERROR: The required disk space is insufficient for the following partitions: 

/ - available: <available_space>%, required: 40% 

/opt - available: {opt_available_gb}GB, required: 10GB

/var/log/ - available: <available_space>%, required: 20%

Resolution

The space used in the OS(/) partition should not be more than 60%. If the space used is more than 60%, then you must clean up the OS(/) partition before proceeding with the patch installation process. For more information about cleaning up the OS(/) partition, refer here.

For increasing the /opt partition, perform the steps using Increasing the Appliance Disk Size.

For increasing the size of /var/log directory, perform the steps using Extending the Logs Volume.

Issue: Expected ESA version

ERROR: Expecting appliance version 10.1.x/10.0.x/9.2.0.x/9.1.0.x. Current ESA version {appliance_version}

Resolution

This patch must be applied on any of the following versions:

  • 9.1.0.x
  • 9.2.0.x
  • 10.0.x
  • 10.1.x

Issue: Missing IP address in Unicast hosts file

ERROR: Unicast hosts file does not contain the IP addresses of the nodes and is empty.  Run the Audit Store Management Unicast Hosts scheduled task.

Applicable Version: 9.1.0.x

Resolution

To run the Audit Store Management Unicast Hosts scheduled task:

  1. Log in to the ESA WebUI.

  2. Navigate to System > Task Scheduler.

  3. Select the Audit Store Management Update Unicast Hosts task.

  4. Click Run now!.

    In some ESA versions, the task is named as Audit Store Management - Cluster Config - Sync.

Issue: Unicast hosts file verification failed

ERROR: Unicast IP verification failed. IPs in cluster: {node_ips} IPs in unicast hosts file: {ips}. Verify the entries in the {UNICAST_HOSTS_FILE} file.

ERROR: Unicast hostname verification failed. Retrieved hostname: {hostname}. Verify the entries in the {UNICAST_HOSTS_FILE} file.

ERROR: Unicast hosts file is empty. Please add the IP and hostname entries for all the nodes in the Audit Store cluster in the Unicast hosts file /opt/protegrity/auditstore/config/unicast_hosts.txt

ERROR: Unicast hosts file not found. {UNICAST_HOSTS_FILE}. Create the file with the relevant node IPs.

Applicable Version: 9.2.0.x, 10.x

Resolution

Update the unicast hosts file:

  1. Obtain the IP and hostname entries of all the ESA nodes in the Audit Store cluster.
  2. Log in to the CLI Manager on the ESA.
  3. Navigate to Administration > OS Console.
  4. Enter the root password.
  5. Navigate to /opt/protegrity/auditstore/config.
  6. Open the unicast_hosts.txt file using a text editor.
  7. Add and verify the node entries in the file.
  8. Save and close the file.

Issue: Analytics is not initialized

ERROR: Analytics is not initialized. Please initialize analytics.

Resolution:

Initialize Analytics.

  1. Log in to the ESA Web UI.
  2. Verify that the Audit Store services are running by navigating to System > Services > Audit Store.
  3. Navigate to Analytics. For ESA v10.x, navigate to Audit Store > Initialize Analytics.
  4. Click Initialize Analytics.

Issue: Insight services not running

ERROR: Analytics service is not running. Please start the service.

ERROR: Audit Store Dashboards service is not running. Please start the service.

ERROR: Audit Store Management service is not running. Please start the service.

ERROR: Audit Store Repository service is not running. Please start the service.

ERROR: Audit Store connection failed, cluster verification cannot proceed.

ERROR: Audit Store connection failed, unicast file verification cannot proceed.

ERROR: Audit Store connection failed. Audit Store Repository service is not running. Please start it to proceed.

ERROR: Audit Store connection failed. Audit Store Repository took too long to respond (00:00:30). <exception-Connection Error>

ERROR: td-agent service is not running. Please start the service.

Resolution:

Enable the Run the following steps to resolve the issue.

  1. From the ESA Web UI, navigate to System > Services > Audit Store.
  2. Ensure that the Audit Store Repository service is running.
  3. Open the ESA CLI.
  4. Navigate to Tools.
  5. Run Apply Audit Store Security Configs.

Issue: Audit Store connection failed due to certificates

ERROR: Audit Store connection failed. Certificated expired. Please upload valid certificate.

Resolution:

Upload valid certificates using the steps provided in Uploading Certificates and Insight Certificates.

Issue: The master or repository keys are expired

Validate that master/repository keys are not expired with respect to OUP

"ERROR: Call to check key state failed. Please verify that all services are running" (when hubcontroller is down)

"ERROR: Master or repository key is expired, please rotate the key(s)"

Resolution:

  • If the security keys, such as, master key or repository key have expired or are due to expire within 30 days, then the upgrade fails. Hence, the keys must be rotated before performing the upgrade. Additionally, ensure that the keys are active and in running state.

    For more information about rotating keys, refer to Working with Keys.

  • If you are using an HSM, ensure that the HSM is accessible and running.

    For more information about HSM, refer to the corresponding HSM vendor document.

If the prerequisites are not met, the ESA upgrade process fails. In such a case, it is required to restore the ESA to its previous stable version.

Issue: The active Key Store health check failed

Validate that Key Store is healthy

"ERROR: Call to check HSM health failed. Please verify that all services are running" (when kmgw/ soft hsm service is down)

"ERROR: The health check for active HSM GW instance is failing, please make sure HSM is accessible"

Resolution:

Test the Key Store connection to validate where the Key Store can be accessed using the steps from Key Store Management.

Issue: The license is invalid or expired

Validate that license is valid (expired/invalid)

"ERROR: License is not valid"

"ERROR: Failed to check license. Please verify that Policy Management services are running" (when hubcontroller is down)

Resolution:

Before upgrading the ESA, ensure that the license is not expired or invalid.

An expired or invalid license blocks policy services on the ESA and Devops API’s. A new or existing protector will not receive any policies until a valid license is applied.

For more information about the license, refer Protegrity Data Security Platform Licensing.

Warning: List of unsupported protectors connected with the ESA

Check for unsupported protectors
Installation pre-checks have detected protector versions that under specific circumstances pose a potential risk

"ERROR: Failed to list unsupported protectors" (When hubcontroller is down)

Resolution:

The ESA v10.2.0 only supports protectors having the PEP server version 1.2.2+42 and later.

During the upgrade, the process checks if any unsupported protector is registered in the system.
If the Installation pre-check script detects any protector that is not supported by the ESA v10.2.0, then the Warning dialog box appears.

You can either terminate the Upgrade process or you can continue with unsupported protectors.

It is recommended to upgrade the protectors to a supported version before proceeding with the Upgrade process.

Perform the following steps to identify the PEP server version of the protector:

  1. Log in to the ESA.
  2. Navigate to Policy Management > Nodes.
  3. View the Version field for all the protectors.

If the protector version is unsupported, perform one of the following actions:

  • Uninstall the unsupported protector and delete the node from the list of registered nodes.
  • Upgrade the unsupported protector to a supported version. For most of the protectors, this process involves uninstalling and installing the protectors. However, some protectors, such as Data Security Gateway (DSG) and Big Data Protector (BDP), might support the upgrade process. The new installed protector updates the registered node entry.

Issue: DTP/DTP2 data elements are present

Validate that no DTP/DTP2 data elements are present

"ERROR: Found unsupported DTP data elements"

"ERROR: Failed to establish a new connection to the HubController service"

Resolution:

If the DTP/DTP2 is present in the algorithm property of a data element while upgrading from the ESA v9.1.0.x or later versions to ESA v10.2.0, then the upgrade script fails. The following error message appears:

ERROR: Found unsupported DTP data elements

Perform the following actions:

  1. Reprotect data with a new data element that is supported.
  2. Remove the data elements that contain DTP/DTP2 algorithm.

This prevents the data loss that occurs during the upgrade. The DTP/DTP2 data elements are now unsupported.

For more information about the data elements to be used, contact Protegrity Support.

Issue: FPE data elements are present

Validate that no FPE data elements with left/right > 0 are present

"ERROR: FPE Data Element(s) with characters in clear ('From Left' / 'From Right') are no longer supported on the target version. Please consult the documentation or Protegrity staff for guidance. Data Element(s) affected: "

"ERROR: Failed to list FPE Data Elements"

Resolution:

If the format-preserving encryption (FPE) data elements with Left and Right settings are present while upgrading from the ESA v9.1.0.x or later versions to ESA v10.2.0, then the upgrade script fails. The following error message appears:

ERROR: FPE Data Element(s) with characters in clear ('From Left' / 'From Right') are no longer supported on the target version.  
   Please consult the documentation or Protegrity staff for guidance. 
   Data Element(s) affected: <List of affected data elements>

Perform the following actions:

  1. Reprotect data with a new FPE data element that does not have Left and Right settings or a new data element that is supported.
  2. Remove the data elements that contain Left and Right settings.

This prevents the data loss that occurs during the upgrade. The FPE data elements with Left and Right settings are now unsupported.

For more information about the data elements to be used, contact Protegrity Support.


Last modified : October 31, 2025