Product documentation
Citrix DaaS
View PDF

Monitoring and Troubleshooting

June 9, 2025
Contributed by: 
C

Monitoring Scheduled VDA Upgrades

VDAs and machine catalogs have two attributes to help monitor the readiness and current status of VDA upgrades that are visible as columns that can be used to filter in Studio or in the details pane of the VDAs or catalogs.

  • VDA Upgrade
  • VDA Upgrade State

VDA Upgrade

VDA Upgrade provides information on whether the VDA or machine catalog has the VDA upgrade agent configured and if VDAs are up to date or if an upgrade is available. The available statuses are as follows:

VDA Upgrade (Studio) VDA Upgrade (Powershell) Description
Catalog Level
Not configured MissingUpgradeType An upgrade track (CR, LTSR, CR EAR, or LTSR EAR) has not been selected for the machine catalog.
Scheduled UpgradeScheduled An upgrade is scheduled for the machine catalog.
Available UpgradeAvailable VDAs in the catalog are not on the latest version of the upgrade track. An upgrade is recommended.
Up to date UpToDate VDAs in the catalog are on the latest version of the upgrade track. No action is required.
Unknown Unknown Retrieving the latest VDA Upgrade state.
Machine Level
Not configured MissingUpgradeType An upgrade track (CR, LTSR, CR EAR, or LTSR EAR) has not been selected for the machine catalog of the VDA.
Scheduled UpgradeScheduled An upgrade is scheduled for the VDA.
Available UpgradeAvailable The VDA is not on the latest version of the upgrade track. An upgrade is recommended.
Up to date UpToDate The VDA is on the latest version of the upgrade track. No action is required.
Checking state Unknown Retrieving the latest VDA Upgrade state.

Note:

For VDAs using the LTSR track, a catalog will only show as Up to date if the VDAs are on the latest cumulative update (CU) of the latest long term term service (LTSR) version. If the VDA is on the latest CU of a previous LTSR version, VDA Upgrade will still show as Available.

VDA Upgrade State

VDA Upgrade State provides information on the status of a scheduled upgrade. The VDA Upgrade State statuses are as follows:

VDA Upgrade State (Studio) VDA Upgrade State (PowerShell) Description
Catalog Level
Not scheduled NotScheduled No upgrade is scheduled for the catalog.
Scheduled UpgradeScheduled An upgrade is scheduled for the catalog.
In progress UpgradeInProgress An upgrade is in progress for the catalog.
Canceled UpgradeCancelled An upgrade was cancelled for the catalog. This can be due to a manual cancellation or the failure threshold being reached.
Failed UpgradeFailed A scheduled upgrade for the catalog failed.
Successful UpgradeSuccessful A scheduled upgrade for the catalog completed successfully. Note: A successful upgrade does not mean all VDAs in the catalog upgraded successfully.
- Empty No upgrade scheduled for the catalog.
Machine Level
Scheduled UpgradeScheduled An upgrade is scheduled for the VDA.
Awaiting upgrade UpgradeInUpgradeWindow A scheduled upgrade is active, but the VDA has not started to upgrade yet. See “Concurrency” for more information on how VDA upgrades are load-balanced.
In progress UpgradeInProgress The VDA is currently upgrading.
Canceled UpgradeCancelled A scheduled upgrade has been cancelled for the VDA before the upgrade began.
Upgrade failed UpgradeFailed The VDA began to upgrade but the upgrade failed to complete successfully. See “troubleshooting” for more information.
Succesful UpgradeSuccess The VDA upgraded successfully.
Validation failed UpgradeValidationFailed Certificate validation failed while downloading the metadata for the VDA installer.
- Empty No upgrade is scheduled for the VDA.

Troubleshooting Scheduled VDA Upgrades

If you encounter upgrade failures, the following logs can help you identify and troubleshoot the issues. You can also share these logs with Citrix Technical Support to expedite the assistance process.

VDA Installation Logs

When troubleshooting upgrade failures, gather and review the logs for both the initial installation of the VDA and the failed upgrade. Logs for installation and upgrades can be found in the following locations.

  • Installation logs for VDA installations are placed in:
    • %temp%/Citrix/XenDesktop Installer
  • Upgrade logs for VDA installations are placed either in:
    • C:\Windows\Temp\Citrix\XenDesktop Installer or
    • C:\Windows\SystemTemp\Citrix\XenDesktop Installer

VDA Upgrade Agent Version

When gathering data to troubleshoot upgrade failures through VUS, it is important to know the version of the upgrade agent on the VDAs. To check VDA Upgrade Agent versions, use the following cmdlet: Get-VusComponentVersion -ComponentType VUS. It lists all VDAs and their VDA Upgrade Agent versions.

To check VDA Upgrade Agent versions at a catalog level, you can use the following script:

Note:

The script is intended as an example and might need to be adapted to suit your specific environment. We recommend that you test the script thoroughly before using it in a production environment.

Param( [Parameter (Mandatory=$true)] [string] $CatalogName ) try { $Uuids = Get-BrokerMachine -CatalogName $CatalogName | Select-Object -Property UUID

if($Uuids -eq $null) { throw "Cannot find CatalogName " +$CatalogName } Write-Output("Catalog Name passed is "+$CatalogName)

foreach($Uuid in $Uuids) { $compVersion = Get-VusComponentVersion -MachineId $machine.UUID -ComponentType VUS $Machine = Get-BrokerMachine -UUID $compVersion.MachineId Write-Output(“MachineName: “+$Machine.MachineName+”, Machine UUID:”+$machine.MachineId+”, VUA Version:”+$compVersion.Version) } } catch { Write-Output(“Exception Occured”) Write-Host $_ }

VDA Upgrade Agent (VUA) logs can provide essential information for troubleshooting upgrade failures and issues with the VUA communicating with the VDA upgrade service. Logs you can collect include:

  • Citrix Diagnostic Facility (CDF) traces. The CDF module name is VdaUpgradeAgent.
  • Windows event logs. View logs in the Event Viewer > Windows Logs > Applications > Citrix VDA Upgrade Agent Service.

For VUA versions 7.44 and later

In the VDA Upgrade Service Agent version 7.44 (included in the 2503 release), a registry setting is available that allows administrators to enable a rotating log file that captures critical information for troubleshooting while preventing the log files from growing too large. The total size of log files is capped at 20 MB. Create the following registry key to enable logging to a file:

  • Key: HKLM\SOFTWARE\Citrix\UpdateServices\UpdateAgent\LogToFile

  • Value name: LogToFile

  • Value type: REG_DWORD

  • Value data:

    • 0 - file tracing disabled

    • 1 - file tracing enabled

To create the LogToFile registry key on a VDA using PowerShell, use the following cmdlet:

New-ItemProperty -Path HKLM\SOFTWARE\Citrix\UpdateServices\UpdateAgent\LogToFile -Name LogToFile -Value 1 -PropertyType DWord -Force

To enable LogToFile for groups of machines at scale, consider creating the LogToFile registry on all VDA organizational units (OUs) through Group Policy Preference.

Note:

When LogToFile=1 is set, logs are written only to the file. They will not appear in the CDF traces.

For VUA versions before 7.43

If needed, you can modify the VDA Upgrade Agent configuration file so that the logs are continuously written to a file. To enable logging to a file, follow these steps:

  1. Go to the folder C:\Program Files\Citrix\CitrixUpgradeAgent.
  2. Open the file Citrix.UpdateServices.UpdateAgent.exe.config.
  3. Change the value of LogToFile to 1.
  4. Restart the Citrix VDA Upgrade Agent service. This creates a log file at: C:\ProgramData\Citrix\Update Services\Logs.

Note:

  • Enabling logging to a file through the .config file continuously writes logs, potentially consuming storage space. Remember to disable logging after the issue is resolved. To disable logging, first set LogToFile to 0 and then restart the Citrix VDA Upgrade Agent Service.
  • When LogToFile=1 is set, logs are written only to the file. They will not appear in the CDF traces.

Troubleshoot VDA upgrade download failures

Follow the steps below to troubleshoot and resolve download failures related to the VDA upgrade feature:

  1. Make sure that relevant URLs have been added to the allow list if URL filtering is in place. See VDA upgrade requirement.

  2. After adding the necessary URLs to the allow list, try rescheduling the VDA upgrade.

You can enable CDF tracing or set LogToFile to 1 to capture detailed logs for analysis. If the download failure issue persists, check the errors. If you see the following error message “Download Failed: This access control list is not in canonical form and therefore cannot be modified,” it indicates that the permissions on the folder C:\ProgramData\Citrix\UpgradeServices\Downloads\VDA are incorrect.

To address the issue, do either of the following:

  • Option 1: Reset access control lists (ACLs) on the folder using the following command. (The command reset the ACLs with default inherited ACLs for all matching files.)
    • icacls.exe “C:\ProgramData\Citrix\UpgradeServices\Downloads\VDA” /reset /T /C /L /Q
  • Option 2: Delete the VDA folder under Downloads and then schedule the VDA upgrade.

Troubleshoot VDA upgrade validation failures

Follow the steps below to troubleshoot and resolve download failures related to the VDA upgrade feature:

  1. Make sure that relevant URLs have been added to the allow list if URL filtering is in place, especially the Certificate Revocation List (CRL) or Online Certificate Status Protocol (OCSP) URLs needed for the revocation check. See VDA upgrade requirement.

  2. After adding the necessary URLs to the allow list, try rescheduling the VDA upgrade.

We suggest enabling CDF tracing or setting LogToFile to 1 to capture detailed logs for analysis. The logs can include the following errors:

  • RevocationStatusUnknown
  • The revocation function was unable to check the revocation status for the certificate.
  • The revocation function was unable to check revocation because the revocation server was offline.

The VDA Upgrade Agent relies on Windows system calls to validate certificates and perform revocation checks. The errors above indicate that the agent is unable to establish a connection to the CRL or OCSP URLs.

The Windows CryptoAPI does not currently support proxy settings. Review the VDAs with Proxy configurations section for configuring your VDA proxies to facilitate outbound CRL calls.

Monitoring and Troubleshooting
June 9, 2025
Contributed by: 
C
June 9, 2025
Contributed by: 
C

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.