App Layering

Known issues

The following issues have been identified in the current release.

App Layering upgrades

  • The App Layering 2005 upgrade package is large enough that older appliances cannot download it automatically. If you are running version 2001 or older, download the package manually from the downloads site.

  • We recommend running the upgrade from a management console in Secure HTTP (HTTPS). If you upgrade while in HTTP, messages do not display in the browser. If that happens, refresh the browser after 20 minutes. (Refreshing won’t cause issues in spite of the message that says not to refresh.) If the upgrade is still running, you get a “service unavailable error.” It is safe to ignore the message and keep refreshing the browser every few minutes until the login page appears.

App Layering appliance and management console

  • When installing the App Layering appliance, you must use the default CPU setting of 4 CPUs.
  • If you use roles in a complex Active Directory environment and logins are slow, assign all roles to explicit users rather than to groups.

The documentation links in the management console open as a blank page in Internet Explorer 11. To get around this issue, paste the link into another browser. The documentation displays correctly.

App Layering agent

By default, the Citrix App Layering Agent runs under the Local System account on the Hyper-V server. If you change the account to anything other than Local System, the agent cannot transfer disks to and from the appliance.

App Layering OS Machine Tools

  • (Release 19.5 only) After upgrading to release 19.5 (or later) from 19.3 (or earlier), be sure to update KMS Office Activation to use Office 2019. When preparing your OS image for layering, download and run the new App Layering OS Machine Tools.

  • (Release 19.1 only) When preparing your OS image for layering, ensure that your KMS Office Activation is triggered at desktop startup. For this release only, download and run the App Layering OS Machine Tools from Release 18.12.

Elastic Layering

  • Microsoft Office cannot be elastically layered due to the way its licenses are integrated with the Windows Store. The Office app layer must be included in the Layered image.
  • When you enable an image with elastic layering, users might be able to view files and directories from other sessions in Windows Explorer. Directories explored in the other session might create folders visible to all sessions that have permission to browse that directory.
  • If you use elastic layer assignments with Windows Server 2008 or Windows 7, create your file share with a sector size of 512. For details about this issue and related operating system updates, see the following:
  • When launching a small set of Universal Windows Platform (UWP) bridge apps on Windows 10 with Elastic Layering enabled, the apps sometimes fail to launch. (ALHELP-15, UNI-71062)
  • When delivering ArcMap 10.7 as an elastic layer, the app takes up to 60 seconds to launch. Normally it takes 3 seconds when delivered as part of the base image. To optimize start times, add a version to the app layer. In the new version of the layer, increase the registry “miss-cache” optimization setting to 100 (decimal) or more, with a max of 250. Create the DWORD value below the Unifltr service key, making sure that the value is decimal and not hex. (ALHELP-387, UNI-74957)

     HKLM\System\CurrentControlSet\Services\Unifltr\MaxMissCacheEntries [DWORD] 100.

User layers

  • Signing on after upgrade starts the Windows First Sign-in screens: When you sign in after upgrading to 4.10 or later, the usual Windows First Sign-in brings the user layer up-to-date with the OS version. The process preserves user layer files.

  • When user layers are enabled on provisioned desktops, MSI installers are blocked from running at system startup: The Layering service must already be running when the MSI file runs. The Layering service runs when a user logs in. If an MSI attempts to run, you get this error:

    The Windows Installer service depends on the Citrix App Layering Guest Service service which failed to start with the following error: The service cannot start, either because it is disabled or because it has no enabled devices associated with it.

Windows 10 support

  • Windows 10, version 20H2 upgrades. If you upgrade the OS layer to Windows 10 20H2 from an earlier release, upgrade directly to Build 19042.630, or later. Upgrading from builds of Windows 10 20H2 released before 11/16/2020 can result in inconsistent image deployments. For example, if you publish images using a template with Generalize Offline selected, the published images may not work correctly.
  • Upgrading requires extra steps when going to a new Windows 10 major release: During the upgrade, Windows 10 can create a recovery volume on the same disk as the OS layer version. Always delete this volume before you finalize the OS layer version. Otherwise, the recovery volume can cause desktops to fail to start correctly. For more information, see App Layering: Windows 10 upgrade can result in new recovery volume partition.
  • If you have generated and applied the App Layering Optimizations.cmd script to a Windows 10 1909 OS layer, the Search option on the Start menu might not work as expected. To avoid this issue, add a version to the OS layer and run the program c:\windows\setup\scripts\Optimize.hta. To build a new Optimizations.cmd script to apply to the new layer version, deselect Disable tablet input service (Section 6, Option M) and select Save File. Before finalizing the OS layer, run the command Powershell Set-Service TabletInputService -startuptype manual to undo the effect of any previous Optimizations.cmd that might have disabled the service.


  • When using the Windows mini-boot disk option, you can specify up to four Prerequisite layers for any given App layer. If an app requires more than four other applications to be present during installation, install multiple apps in one layer. (UNI-69524)
  • When creating a layer (app, OS, or platform) on Windows 7 64-bit, if you select Offload Compositing in the connector configuration, you can have issues adding a version to the layer. An error occurs, and the packaging machine is not created. When Offload Compositing is not selected in the connector configuration, the packaging machine is created. (UNI-82545)
  • Receiving 503 error, “Server Busy issues” from Azure. If you consistently receive this error, follow the steps in CTX310868. This issue happens sporadically, and a solution for it is being tested. (ALHELP-1383)

Citrix Provisioning

  • When you create an image template, the target device hardware settings must match the Windows operating system and platform layer settings. Ensure that the hardware settings on the target device match the operating system and platform layer hardware settings, especially the number of CPUs. If the settings don’t match, you can get a restart required message when you start the published image. (UNI-50799)
  • If you use Provisioning Services, you must disable IPv6 in the OS layer and not in the Platform layer. (UNI-53600)
  • When importing VHDX files published from App Layering to the PVS disk store, you sometimes receive an invalid disk message. Eliminate the error by changing the period (.) characters in the published file name’s date and time. A valid file name contains only one period for the.VHDX file name extension. (UNI-75902)

Citrix Hypervisor

  • When you prepare your operating system image for use in your Citrix Hypervisor, you must open port 5900 to allow console access. (UNI-50846)
  • Always set the Citrix App Layering connector configuration to point to the master node. (UNI-52454)
  • Prerequisite layers:
    • If a machine hangs at boot and a prerequisite layer is selected, one of the layer disks is probably not attached. Ensure that the Citrix Guest Tools are included in either the OS or platform layers.
    • If you are using Prerequisite layers to create either the OS or platform layer, Citrix Tools must be present. Without the tools, the packaging machine fails and you receive a blue screen. Citrix Hypervisor isn’t able to see any devices attached after the DVD drive. The DVD drive is always in the third slot. (UNI-67741)

Citrix Virtual Apps and Desktops (CVAD)

  • When updating CVAD to version 7.15 CU4, you must first install .NET Framework 4.7.1 on a new version of your OS layer, rather than on the platform layer. Installing .NET Framework 4.7.1 on the OS layer ensures that all app layers, platform layers, and images work correctly. The latest Windows updates already include .NET Framework 4.7.1 as part of the updates. (ALHELP-588, UNI-75108)

Google Cloud

  • When importing layers from another platform, you must add a version to the OS layer, and switch to using the new layer version from then on. Otherwise, packaging machines and published images are likely to fail with a blue screen.

  • Google Cloud Connector Configuration. “Check Credentials” should verify Service Account User role. If the service account specified in the Google Cloud connector configuration Service Account JSON key file is different than the service account associated with your selected Instance Template, your service account in the configuration must have the Service Account User role. If it does not, then you receive an error when deploying a machine using that connector configuration. (UNI-82082)

Nutanix Acropolis

  • The following message during app layer creation indicates that the app layer settings specify a platform layer. Do not use platform layers with the app layer’s performance enhancing caching feature. (UNI-67742)


VMware vSphere

  • When creating the OS layer using the Create OS Layer Wizard, Unified Extensible Firmware Interface (UEFI) virtual machines are listed. You cannot, however, create UEFI machines using the wizard. Instead, use the new ImportOsLayer.ps1 script to import the OS onto the new OS layer machine.

VMware Horizon View

  • Elastic layers are only supported with floating desktop pools. (UNI-53442)
  • When creating a Windows 10 or Windows Server 2016 virtual machine on VMware version 6.7, the machine’s boot options default to the Unified Extensible Firmware Interface (UEFI). App Layering does not support UEFI virtual machines. Use the BIOS setting instead. (UNI-69435)
  • VMware Virtual Volumes (VVols) are not supported in App Layering. (UNI-62302)

Microsoft Azure

  • App Layering does not support Azure File storage. For storage in Azure, create an SMB file share or a network file share. (UNI-42272)
  • Managed disks are not supported. When creating a virtual machine in Azure, be sure to select No managed disks.

Microsoft Hyper-V

  • When you configure Elastic Layering in Hyper-V, you must use unmanaged RDS pools (UNI-53545)
  • When creating an app layer, if a platform layer is specified in the app layer settings, you receive an error. Do not use platform layers with App Layering’s caching feature. (UNI-71868, UNI-67743)


  • Creating an OS layer on Hyper-V Server 2019 can result in this error:

    ‘Failed to create VHD. Make sure there is enough space on the share specified in the connector configuration.’

    This error is due to an issue with the Microsoft PowerShell New-VHD cmdlet. We are keeping our eye out for a fix from Microsoft. In the meantime, use the following workaround for this error:

    1. Make sure the Gold VM has no checkpoints.
    2. Make sure the Gold VMs disk is in the same directory path that is configured in the connector config. Example: Local path is D:\Brock
      Gold VM disk is stored in D:\Brock\WIn10Gold\Win10GoldDisk.vhdx