Configure catalog failover (primary and backup catalogs)

Last published : Oct 27, 2026
Catalog failover helps you keep users productive when your cloud platform runs out of capacity. You mark one or more machine catalogs in a delivery group as primary catalogs, and Autoscale powers on machines only from those catalogs. The remaining catalogs in the delivery group become backup catalogs that take over when the primary catalogs cannot provide machines.
When power actions on the primary catalogs fail repeatedly for lack of capacity or quota, Autoscale switches to the backup catalogs for a time that you set. The switch to the backup catalogs is a failover. When the time ends, Autoscale switches back to the primary catalogs. The switch back is a failback.
Catalog failover helps most when you host machines in a public cloud, where a VM size can become unavailable in a region or zone. Without a backup catalog, Autoscale keeps trying to power on machines that the platform cannot start, and users wait for desktops that never appear. With a backup catalog in another region or zone, or with a different VM size, Autoscale serves users from the backup catalog until the primary catalogs recover.
Configure catalog failover with the Broker PowerShell SDK.
Note:
This feature requires the Universal license.
This feature applies to multi-session OS and single-session OS random (pooled) delivery groups. For single-session OS static delivery groups, users are not reassigned to backup machines. See Important considerations.
Currently, you can configure catalog failover only using the Broker PowerShell SDK. The feature is not available in the Studio console or in the REST APIs.
Related information
Autoscale™

How catalog failover works

Autoscale moves a delivery group between its primary and backup catalogs automatically. The following sections explain how Autoscale identifies each catalog, what triggers a failover, what changes during failover, and how the delivery group returns to the primary catalogs at failback.

Primary and backup catalogs

You mark a catalog as primary by adding a tag to the catalog and then setting the AutoscalePrimaryCatalogTagUid property of the delivery group to that tag. Every other catalog that provides machines to the delivery group is a backup catalog. There is no separate setting for backup catalogs.
  • Only the tag on the catalog counts. Adding the same tag to individual machines has no effect.
  • Each delivery group has its own primary catalog tag. A catalog can be primary in one delivery group and a backup catalog in another.
When the delivery group is not in failover, Autoscale manages only machines in the primary catalogs:
  • Autoscale powers on machines only from the primary catalogs. If demand is higher than the primary catalogs can meet, Autoscale does not power on machines from the backup catalogs.
  • Autoscale scale-down powers off only machines in the primary catalogs. If a backup machine is already powered on, for example because an administrator powered it on, Autoscale scale-down does not power it off.
  • Percentage-based pool sizes and capacity buffers are calculated against the machines in the primary catalogs.

What triggers failover

Power action failures trigger failover when the hosting platform reports them as affecting the whole catalog, not one machine. Examples include capacity and quota errors, such as a VM size that is unavailable in a region or zone, or an exceeded subscription quota. Other power action failures do not count.
Each time one of these failures occurs on a machine in a primary catalog, Autoscale counts the failures on all primary catalogs in the delivery group within the failure period. If the count reaches the failure threshold, the delivery group fails over.
  • Failed power actions of every type count, including power actions that an administrator starts.
  • Failures on machines in backup catalogs are not counted.
  • Failures that occur while the delivery group is in failover do not trigger anything at the time. They are counted after failback if they are still within the failure period. See Choose the failover values.

What happens at failover

When a delivery group fails over, Autoscale does the following:
  1. Marks the delivery group as in failover and sets the time when automatic failback is due. This time is the failback delay after failover.
  2. Puts every machine in the primary catalogs into maintenance mode. Machines that are already in maintenance mode keep their current maintenance mode setting.
  3. Manages all machines in the delivery group. Because the primary machines are in maintenance mode, Autoscale in practice powers backup machines on and off.
Schedules, peak and off-peak times, capacity buffers, and power-off delays continue to work as normal. During failover, percentage-based pool sizes and capacity buffers are calculated against all machines in the delivery group.
During failover, machines in the primary catalogs behave as follows:
  • Machines that are already powered on stay powered on. Autoscale does not power off machines in maintenance mode.
  • Existing sessions are not affected.
  • Pooled machines do not accept new sessions.
  • Assigned machines do not accept new sessions. Users can reconnect to existing sessions only if the AllowReconnectInMaintenanceMode property of the delivery group is $true.
  • Power actions that are already queued for these machines are not canceled.
Important:
In single-session OS delivery groups, primary machines that are powered on and in maintenance mode count toward the pool size during failover. As a result, Autoscale might power on fewer backup machines than users need. In multi-session OS delivery groups, machines in maintenance mode are not counted as running.
For example, a single-session OS random (pooled) delivery group has four primary machines, two of them powered on, and four powered-off backup machines. The pool size is 50%. During failover, the pool size is calculated against all eight machines, so the target is four machines. The two powered-on primary machines count toward the target, so Autoscale powers on two backup machines.

Automatic failback

When automatic failback is due, Autoscale does the following within about a minute:
  1. Clears the failover state of the delivery group.
  2. Takes the primary machines out of maintenance mode. Only machines that failover put into maintenance mode are released. See Maintenance mode during failover.
  3. Marks every backup machine that is powered on, turning on, suspended, suspending, or resuming to shut down after use, so that the backup machines drain.
Backup machines that are marked to shut down after use behave as follows:
  • Single-session OS machines stop accepting new sessions immediately and shut down when they have no sessions.
  • Multi-session OS machines continue to accept new sessions until they have no sessions, and then shut down.
  • Backup machines in maintenance mode are marked but not shut down. They shut down after you take them out of maintenance mode, once they have no sessions.

Maintenance mode during failover

Failback releases only the primary machines that failover put into maintenance mode. If you change maintenance mode during failover, the result is as follows:
  • If you turn on maintenance mode for a primary machine using Set-BrokerMachine -InMaintenanceMode $true, the machine stays in maintenance mode after failback.
  • If you turn on maintenance mode for the delivery group, failback no longer releases the primary machines. They leave maintenance mode only when you turn off maintenance mode for the delivery group.
  • If you turn off maintenance mode for the delivery group, maintenance mode is turned off for all machines in the delivery group, including the primary machines. Autoscale then manages those primary machines even though the delivery group is still in failover.
  • Machines put into maintenance mode automatically because of too many failed registrations keep their maintenance mode after failback.
To take a primary machine out of maintenance mode yourself, use Set-BrokerMachine -InMaintenanceMode $false. If the delivery group is still in failover, Autoscale then manages that machine together with the backup machines and can power it on. The same applies to primary machines that you add to the delivery group during failover.

Important considerations

Before you configure catalog failover, review these behaviors and limits:
  • Autoscale does not send alerts or notifications when a delivery group fails over or fails back. Check the state using PowerShell. See Check the failover state.
  • Users are not reassigned to backup machines. In a single-session OS static delivery group, a user whose assigned machine is in a primary catalog cannot start a new session until failback.
  • Catalog failover changes only which machines Autoscale powers on and off. It does not restrict where sessions start. Users can start sessions on any available backup machine that is powered on.
  • If both the primary and the backup catalogs fail, the delivery group stays in failover until automatic failback is due. It then returns to the primary catalogs and fails over again when the failure threshold is reached again.
  • During a Local Host Cache outage, power management does not run, so failover and failback do not happen.

Prerequisites

Before you configure catalog failover, verify these prerequisites:
  • The site must have the Universal license. Otherwise, setting any of the four catalog failover properties fails with a "feature not enabled" error.
  • Autoscale must be enabled for the delivery group.
  • The delivery group must contain at least two power-managed machine catalogs: one or more primary catalogs and one or more backup catalogs.
  • The delivery group must not use Autoscaling tagged machines (cloud burst). If RestrictAutoscaleTagUid is set, the command fails with the error "Autoscale primary catalog configuration is not compatible with Autoscale Cloud burst."

Use PowerShell to configure catalog failover

Configure catalog failover with the following delivery group properties. Set them using the New-BrokerDesktopGroup or Set-BrokerDesktopGroup PowerShell command.
  • AutoscalePrimaryCatalogTagUid – The UID of the tag that marks the primary catalogs. $null turns off the feature for the delivery group. The default value is $null.
  • AutoscalePrimaryCatalogFailureThresholdPerPeriod – The failure threshold. The delivery group fails over when the number of failures within the failure period reaches this value. The default value is 0.
  • AutoscalePrimaryCatalogFailurePeriodMinutes – The failure period. The length of time, in minutes, in which failures are counted. The default value is 0.
  • AutoscalePrimaryCatalogAutomaticFailbackMinutes – The failback delay. The time, in minutes, from failover until automatic failback. The default value is 0.
Set each numeric value to 0 or greater. The values have no upper limit.
Important:
Always set all three numeric values when you set the primary catalog tag. With the default values of 0, the delivery group fails over on the first failure and fails back within about a minute.
To use the PowerShell SDK directly, complete the following steps:
  1. Create a tag. Use the New-BrokerTag PowerShell command to create a tag.
  2. Apply the tag to the primary catalogs. Use the Add-BrokerTag PowerShell command to add the tag to each catalog that you want to be primary.
  3. Assign the tag to the delivery group and set the failover values. Use the Set-BrokerDesktopGroup PowerShell command.
    • For example:
      Set-BrokerDesktopGroup -Name "MyDeliveryGroup" -AutoscalePrimaryCatalogTagUid $tag.Uid -AutoscalePrimaryCatalogFailureThresholdPerPeriod 3 -AutoscalePrimaryCatalogFailurePeriodMinutes 30 -AutoscalePrimaryCatalogAutomaticFailbackMinutes 240
      In this case, the delivery group fails over when three failures occur within 30 minutes, and fails back automatically 240 minutes after failover. Every other catalog that provides machines to "MyDeliveryGroup" is now a backup catalog.
    • For more information about the Set-BrokerDesktopGroup PowerShell command, see https://citrix.github.io/delivery-controller-sdk/Broker/Set-BrokerDesktopGroup/.
Warning:
  • If the tag is not on any catalog in the delivery group, Autoscale has no machines to manage when the delivery group is not in failover. The PowerShell command does not check this. To see which catalogs carry the tag, run Get-BrokerCatalog -Tag "PrimaryCatalog".
  • If every catalog in the delivery group is a primary catalog, all machines go into maintenance mode at failover and no machines are powered on until failback.

Choose the failover values

Follow these recommendations when you set the values:
  • Set the failure threshold to a value greater than 1. A value of 0 or 1 fails the delivery group over on the first failure.
  • Set the failure period to a value greater than 0. A failure period of 0 with a failure threshold of 1 or more can prevent failover.
  • Set the failure period to less than 3 days (4,320 minutes). Completed power actions are kept for 3 days by default, and failures older than that cannot be counted. If your site keeps completed power actions for a different time, set the failure period shorter than that time.
  • Set the failback delay longer than the failure period. Failover and failback do not clear the failure history. If the failback delay is shorter than the failure period, failures from before the failover are still counted after failback, and a single new failure can cause the delivery group to fail over again. See Example scenario.

Check the failover state

Use the following properties of Get-BrokerDesktopGroup to check the state:
  • IsAutoscaleCatalogFailoverActive – True while the delivery group is in failover and Autoscale uses the backup catalogs.
  • AutoscalePrimaryCatalogFailoverExpiryTime – The time, in UTC, when automatic failback is due. $null when the delivery group is not in failover.
For example:
Get-BrokerDesktopGroup -Name "MyDeliveryGroup" | Select-Object Name, IsAutoscaleCatalogFailoverActive, AutoscalePrimaryCatalogFailoverExpiryTime
To list all delivery groups that are in failover:
Get-BrokerDesktopGroup -IsAutoscaleCatalogFailoverActive $true
To list the primary machines that failover put into maintenance mode:
Get-BrokerMachine -DesktopGroupName "MyDeliveryGroup" -MaintenanceModeReason AutoscalePrimaryCatalogFailover
After automatic failback, backup machines that are draining have WillShutdownAfterUse set to True. To list them, look for machines in the backup catalogs:
Get-BrokerMachine -DesktopGroupName "MyDeliveryGroup" -WillShutdownAfterUse $true | Select-Object MachineName, CatalogName

Fail back manually

To fail back before automatic failback is due, use the Reset-BrokerAutoscaleCatalogFailover PowerShell command. Manual failback clears the failover state and takes the primary machines out of maintenance mode, the same as automatic failback. Specify the delivery group by UID with -DesktopGroupUid, or pass the delivery group from the pipeline.
For example:
Get-BrokerDesktopGroup -Name "MyDeliveryGroup" | Reset-BrokerAutoscaleCatalogFailover
Important:
Manual failback does not mark backup machines to shut down after use. Backup machines that are powered on stay powered on, and Autoscale scale-down does not power them off because it manages only the primary catalogs again. Shut down these machines yourself after their users log off, for example using the New-BrokerHostingPowerAction PowerShell command with -Action Shutdown.

Turn off catalog failover

To turn off catalog failover for a delivery group, clear the primary catalog tag:
Set-BrokerDesktopGroup -Name "MyDeliveryGroup" -AutoscalePrimaryCatalogTagUid $null
After you clear the primary catalog tag, you can configure cloud burst for the delivery group. See Autoscaling tagged machines (cloud burst).

Example scenario

Suppose you have the following scenario:
  • Machine catalog configuration. Two Azure MCS catalogs that use the same master image and VM size in different Azure regions. "Primary-Catalog" contains machines M1 to M5. "Backup-Catalog" contains machines M6 to M10.
  • Tag configuration. The tag "PrimaryCatalog" is applied to "Primary-Catalog."
  • Delivery group configuration. "MyDeliveryGroup" is a single-session OS random (pooled) delivery group that contains all 10 machines, with AutoscalePrimaryCatalogTagUid set to the UID of the "PrimaryCatalog" tag.
  • Autoscale configuration. During peak times, the pool size is five machines and the capacity buffer is 0%.
  • Failover configuration. Failure threshold 3, failure period 30 minutes, failback delay 240 minutes.
The scenario runs in the following sequence:
  1. Peak time starts.
  2. Azure runs out of capacity for the VM size in the primary region.
  3. The delivery group fails over.
  4. Automatic failback is due.
The following steps describe how Autoscale behaves at each stage:
  • Peak time starts
    • Autoscale powers on machines only from Primary-Catalog to meet the pool size of five machines. M1 to M3 power on.
    • M6 to M10 stay powered off.
  • Azure runs out of capacity
    • At 10:00, Autoscale tries to power on M4 and Azure returns an allocation failure. One failure has occurred in the last 30 minutes.
    • At 10:05, another power-on fails. Two failures have occurred in the last 30 minutes.
  • The delivery group fails over
    • At 10:12, a third power-on fails. Three failures have occurred in the last 30 minutes, which reaches the failure threshold.
    • IsAutoscaleCatalogFailoverActive becomes True, and AutoscalePrimaryCatalogFailoverExpiryTime is set to 240 minutes later (14:12).
    • M1 to M5 are put into maintenance mode. M1 to M3 stay powered on and their existing sessions continue, but they do not accept new sessions.
    • M1 to M3 count toward the pool size, so Autoscale powers on two machines from Backup-Catalog, M6 and M7, to reach five machines. New sessions start on M6 and M7.
  • Automatic failback is due
    • At 14:12, Autoscale fails back within about a minute. The failures from 10:00 to 10:12 are no longer within the 30-minute failure period.
    • M1 to M5 leave maintenance mode. M1 to M3 are still powered on, and Autoscale powers on machines from Primary-Catalog again to meet the pool size.
    • M6 and M7 are marked to shut down after use. Each one stops accepting new sessions and shuts down after its user logs off.
Now suppose the failure period is 60 minutes and the failback delay is 20 minutes, which is shorter than the failure period:
  • Failures at 10:00, 10:10, and 10:20 reach the failure threshold. The delivery group fails over at 10:20, and automatic failback is due at 10:40.
  • At 10:40, the delivery group fails back.
  • At 10:45, one new failure occurs. The failures at 10:00, 10:10, and 10:20 are still within the 60-minute failure period, so there are now four failures and the delivery group fails over again 5 minutes after failback.

More information