App Layering

Known issues

App Layering 2306

Upgrading to App Layering 2306 might fail, returning the error “A failure occurred while upgrading the appliance. Please try the upgrade again after reverting from a clean snapshot.” We are aware of an issue with some appliances that were upgraded from previous versions. In this scenario, the upgrade might fail due to the presence of legacy upgrader components. We are working on a patched build for App Layering 2306 that contains a permanent fix for this issue.

To work around this issue, it is necessary to remove the legacy module by making the following changes in the Layering appliance:

  1. Log in to the appliance console using the root login and password.
  2. Run the command “yum remove mod_http2”. It might take several minutes for the command to run.
  3. After the command completes, log back into the appliance using a web browser and rerun the upgrade.
  4. It might take 30 minutes or more for the upgrade to complete, but it should now succeed.

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 despite 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.

  • If you have two upgrade packages with the same name in different folders in Network File Share, selecting one of those packages causes both packages to be selected. If both packages have the same version, the upgrade succeeds. If they have different versions, the system chooses the lower version number. This occurs with Enterprise Layer Manager (ELM) version 22.2.

App Layering appliance and management console

  • In the new UI, platform types cannot be edited. Edit Platform Types still functions correctly in the old UI. (UNI-86856)
  • 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.


A login or logout failure might occur when FSLogix uses Cloud Cache locations for profile or ODFC containers along with App Layering Elastic Layers. A pop-up screen displays login failures and a frozen logout screen displays logout failures. FSLogix log files located at c:/ProgramData/FSLogix/Logs/Profile/Profile-YYYYMMDD.log also display the following error message for login failures: "ERROR:00000005 Access is denied" errors at various points during the login attempt.


Exclude the C:\ProgramData\FSLogix\ folder tree from App Layering’s management. To do this,

  1. Create an exclusion file on the layer containing the FSLogix installation by creating a .txt file in C:\Program Files\Unidesk\Uniservice\UserExclusions with a name like FSLogix.txt. The published image processes all files in this location ending with a .txt. extension.

  2. In the newly created file, place one line: c:\ProgramData\FSLogix\ The trailing ‘ \ ‘ is required to indicate the FSLogix folder tree should be excluded (not just the FSLogix folder itself). Also, no quotes must be present even if the path contains spaces.

  3. Finalize the layer and use this new revision in future deployments.


It is safe to use these exclusions even if you are not using the Cloud Cache feature.

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 might 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 Issue 9 under Windows 10 v2004, 20H2, 21H1 & 21H2 - Citrix Known Issues.
  • 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 Azure Deployments connector, if you delete all templates and edit the connector to choose a new template, a deleted template version appears. Then when you click Save, an error appears. As a workaround, reselect a valid template version before clicking Save. (UNI-88412)
  • 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)
  • If you attempt to enter a name for a connector, and that name already exists, you receive a generic error message from the system, rather than the correct error message. The issue occurs for the Azure Deployments, Machine Creation for Azure Deployments, VMware vSphere, and Machine Creation for vSphere connectors. (UNI-89218)

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)
  • When Offload Compositing is selected in the connector configuration:
    • The path for the Citrix Provisioning Store fails to validate if it contains spaces. Replace the spaces with %20 to make the name valid. (UNI-84868)
    • Publish jobs fail if the File Share Path ends with a backslash (\). (UNI-85045)
    • Publish jobs fail with a ComponentActivator error message if the Domain User does not have Read and Write permission to the File Share Path. (UNI-85020)
  • When you select a Hyper-V connector for the offload compositing configuration, and the OS Layer is Gen 2, you must create another version of the OS layer, and then create the platform layer from that OS version. Otherwise, the target does not boot. (UNI-85044)
  • When setting the Compositing File Share Path for the connector configuration, connectivity between the compositing engine and the Citrix Provisioning Store is not verified. If the store path doesn’t map to the File Share Path, you receive an error similar to:

    • Error: “An unexpected system error occurred. Retry the operation or contact technical support. Exception Message: Response status code does not indicate success: 404 (Not Found). [Exception Details] (UNI-85045), (UNI-85020)

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” verifies 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.
  • When using a vSphere connector configuration with VMware Cloud and a vSAN 7.0 Update 2 (or later) datastore, Offload Compositing must be selected. (UNI-85216)
  • When using the new VMware vSphere connector in AL 23.4, if you select an opaque network when creating or editing the connector, the connector fails. As a workaround, select a non-opaque network. Existing connector configurations using an opaque network created before AL 23.4 continue to function normally. (UNI-89439)

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 only supported for OS imports. Packaging app layers and publishing images only produce unmanaged disks. When creating a virtual machine in Azure, select No managed disks.

Microsoft Hyper-V

  • When selecting a Hyper-V connector configuration for Offload compositing and your OS layer is Gen 2, the layer must have at least one version besides the original. Also, the platform layer where the Citrix Provisioning target device software is installed must be created using the new OS layer version. (UNI-85044)
  • When a Hyper-V connector configuration is set for Offload Compositing with Gen 2 (UEFI) and VHDX, choosing VHD as the Disk Format in the Citrix Provisioning connector configuration is allowed, but this configuration is not supported.
  • 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
  • App Layering fails to create an app/platform layer if the path to storage in the Hyper-V connector configuration contains a backtick (`). For example: