Citrix CVAD 2402 DDC Upgrade Fails (CU2 to CU3) via Command Line due to License Server Certificate Hash Mismatch

book

Article ID: CTX696183

calendar_today

Updated On:

Description

When upgrading an on-premises Citrix Delivery Controller (DDC) from version 2402 CU2 to 2402 CU3, the process may fail with a certificate validation error. This issue specifically impacts automated or scripted deployments, while the graphical user interface (GUI) installer typically completes without interruption.

The upgrade failure is triggered by a mismatch in the License Server (LS) Certificate Hash. During the pre-installation check, the installer attempts to verify the identity of the License Server to ensure secure communication. If the hash provided or stored does not align with the live certificate, the upgrade terminates.

  • The issue is exclusive to Command Line (CLI) upgrades. GUI-based installations handle the certificate handshake differently and are not affected.

  • Intermittent Occurrence: The failure does not occur in all CLI environments, suggesting it may be linked to specific certificate renewal histories or existing site configurations

 

Cause

It is likely that CitrixLicensing.exe was executed multiple times, which may have triggered an unintended uninstallation and reinstallation of the Licensing Server, resulting in a change to the certificate hash.

The fundamental cause is a discrepancy between the actual certificate hash currently presented by the License Server and the stored hash within the Citrix Site Configuration or the Windows Registry.

During a CLI upgrade, the installer passes the stored hash as a parameter. If the LasVerificationTool detects that the live certificate on port 8083 does not match the string provided in the command line, it triggers IDS_CANNOT_CONNECT as a security precaution.

 

Source Location
Registry image.png
PowerShell Get-ConfigSite (MetadataMap :LicenseServerCertificateThumbprint)

 

Resolution

Log Analysis:

Detailed investigation of the upgrade logs reveals that the failure begins with a connectivity validation error, followed by the specific hash mismatch code.

 

Relevant Log Snippet:

2026-01-13 11:40:50 : Running command: .\LasVerificationTool.exe -u https://ctxls01.domain.com:8083/ ... -h [HashValue] 2026-01-13 11:40:50 : Output: Check compatibility failed, response, Error : , Internal : Contact License Server - Failed Main: Process: returns IDS_CANNOT_CONNECT

XML Response Breakdown: The LasVerificationTool.exe generates an XML response confirming that while the host might be reachable, the security parameters are rejected:

  • ReturnCode -18: "License Server cert hash does not match the pass in hash."

  • ReturnCode -10: "Cannot connect to license server host."

 

Solution: Resolving the License Server Certificate Hash Mismatch

If you encounter the "License Server Cert Hash does not match" error during a command-line upgrade of the Delivery Controller (DDC) to 2402 CU3, follow these steps to synchronize the certificate thumbprints and successfully complete the installation.

Method 1: Restoring and Re-synchronizing (Recommended)

This approach is necessary if CitrixLicensing.exe was run multiple times, causing a mismatch between the License Server (LS) state and the Site Database.

  1. Revert to CU2: Restore the License Server to its 2402 CU2 state using a VM snapshot.

  2. CLI Upgrade of LS: Perform the upgrade of the License Server to CU3 using the standalone CitrixLicensing.exe via the command line.

  3. Upgrade DDC: Execute the DDC upgrade using XenDesktopServerSetup.exe. The installer should now recognize the synchronized hash and proceed.

Method 2: Manual Clean Reinstall (No Snapshot Available)

If a snapshot is unavailable, you must manually reset the Certificate Hash sync between DDC and License Server.

  1. Uninstall: Remove the CU3 License Server software and restart the machine.

  2. Reinstall CU2: Install the 2402 CU2 License Server using the XenDesktopServerSetup.exe media.

  3. Force Synchronization: * Open Citrix Studio to initialize the connection.

    • Open the Citrix Licensing Manager. This sequence forces the DDC to sync the current Certificate Hash to the Site Metadata and Database.

  4. Final Upgrade: Proceed with upgrading the License Server to CU3 via CLI, followed by the DDC upgrade.

Method 3: PowerShell Synchronization (Advanced)

Instead of reinstalling software, you can manually update the Site Metadata to match the current License Server certificate hash using the following PowerShell commands:

# 1. Retrieve the current hash from the License Server

$certhash = (Get-LicCertificate -AdminAddress "LS_FQDN:27000").CertHash 

# 2. Update the Site Metadata with the retrieved hash

Set-ConfigSiteMetadata -AdminAddress "DDC_FQDN:80" -Name "CertificateHash" -Value $certhash

Important Considerations

  • When is Sync Required? Manual synchronization or opening Studio is generally only required if the License Server has been uninstalled or reinstalled. In a standard in-place upgrade, the Certificate Hash typically remains unchanged.

  • Backup First: Always ensure you have a fresh backup of your Site Database before modifying Site Metadata via PowerShell.

Issue/Introduction

When upgrading a Citrix Delivery Controller (DDC) from version 2402 CU2 to 2402 CU3, administrators may encounter a specific roadblock involving the License Server (LS) certificate. While the GUI-based installer handles this transition smoothly, the automated or command-line (CLI) approach may trigger a failure.

 

Powered by Wolken Software