Citrix - Troubleshooting and Limitations

General Limitations

  • The Citrix registry patch is installed when you record or replay a Citrix Vuser script for the first time. In rare situations, the error log will indicate that it could not be installed. In this case, try to install the registry patch manually. The patch can be found at: <installation_folder>\dat\Enable_Citrix_API.reg. To install the registry patch, double-click Enable_Citrix_API.reg on the relevant machine.

    Note: The Citrix client is 32-bit software. Therefore, on a 64-bit OS, install this registry patch under HKLM\SOFTWARE\Wow6432Node\ , and not under HKLM\SOFTWARE\ . To do this, launch Enable_Citrix_API.reg from the 32-bit file manager or modify it before launching it from Windows Explorer."

  • Running Citrix Vusers on virtual machines may adversely affect performance due to the sharing of physical resources.

  • Text recognition may not work correctly for overlapped windows on Windows 2012 servers.

  • On Windows 8.1, in replay, the Start menu may not appear after clicking on the Start button.

    Workaround: Add another ctrx_mouse_click function into the script below the recorded ctrx_mouse_click or ctrx_obj_mouse_click functions.

  • The Citrix agent does not provide support for Java applications on x86 operating systems.
  • If an ICA script succeeds in VuGen, but fails when running on a Load Generator, check the display on the Load Generator machine. If it displays a Citrix dialog box entitled, ICA Client File Security, then, in the Access section of the dialog box, select Full Access and Never ask me again for any application. Click OK to apply your changes.

    Note: You can also set these options in WebICA.ini. For details, see:

  • The Citrix agent cannot capture text from Java-based applications or from Internet Explorer 9 and later.
  • The Citrix agent cannot capture text from certain Java controls with overlapping text boxes, such as dropdown and combo boxes.

  • The recording window size option does not work properly with the Plugin for Hosted Applications 11. The size of the client window is captured, but the server screen resolution is not. This is a Citrix Client limitation and may be fixed in future Citrix Client versions.

    Workaround: When recording, set the window size equal to the local screen resolution. When replaying/load testing, set the VuGen or Load Generator screen resolution to equal the resolution used when the script was recorded. To verify the recorded resolution, view the Window property in the <Script Folder>\default.cfg file.

  • The Citrix Connection Center may prevent record and replay of Citrix ICA scripts, if it is running in a different user session on the same machine.

    Workaround: Close all instances of the concenter.exe process for all users. To prevent the Citrix Connection Center from starting automatically, set the ConnectionCenter registry key to an empty value. This key can be found at:
    For 32-bit systems: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Run
    For 64-bit systems: HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Windows\Curr

    • On a machine with Citrix Receiver 14.4 installed, it is not possible to connect to the Citrix server during record/replay for a single-protocol Citrix script, if connection details have been specified manually in Recording Options > Citrix > Login. (This may also apply for later versions of Citrix Receiver.)
      There is no issue with Citrix Receiver 14.4 for Citrix single-protocol scripts with ICA files, or Citrix multi-protocol scripts.

  • On a machine with Citrix Receiver 13.0-14.6 installed, ctrx_mouse_move() does not work.

    Workaround: Do one of the following:

    • Change the script to use an alternative UI flow. That is, replace mouse-move operations with other operations, such as keyboard operations.

    • Upgrade the Citrix Receiver client (both locally and on the Load Generator machine) to Citrix Receiver version 4.7. Then modify the following Windows registry keys to enable the solution:

      OS Registry keys
      32-bit Key location: LOCAL_MACHINE\SOFTWARE\Citrix\ICA Client\CCM
      • Key location: LOCAL_MACHINE\SOFTWARE\Wow6432Node\Citrix\ICA Client\CCM
      • Name: AllowMouseEvent
      • Type: REG_DWORD
      • Value: 1

Back to top

Effects and Memory Requirements of Citrix Agent

When you run Citrix Vusers with the agent installed, each Vuser runs its own process of ctrxagent.exe. This results in a slight reduction in the number of Vusers that can run on the server machine (about 7%).

When the agent is installed, the memory requirements per Citrix Vuser is approximately 4.35 MB. To run 25 Vusers, you would need 110 MBs of memory.

Back to top

Random Failures of Functions Accessing Citrix Agent

Communication between Citrix Server and Citrix client-side software is directed via Citrix ICA Virtual Channels. This is a bi-directional connection for the exchange of packet data.

Each Vuser opens its own instance of HPE Citrix Agent on the server side, and, respectively, its own virtual channel. Citrix Virtual Channels may become unreliable under high load. As a consequence, functions that rely on Citrix Agent API (ctrx_get_text(), ctrx_sync_on_obj_info() etc.) may fail randomly.

Workaround: Use a TCP channel for communication with the Citrix Agent. Set the following flags:

TCPChannel=1 in the [CITIRX] section of the script’s default.cfg configuration file,

TcpChannelEnabled=1 in the [ChannelConfig] section of the CtrxAgent.ini file.

Note that for MinPortValue and NumPorts flags in CtrxAgent.ini, the agent tries to find a free port and enumerates NumPorts ports starting from MinPortValue. If you have firewall software on the Citrix server or load generator, make sure to configure it to allow connections on these ports.

Back to top

Citrix Agent will not start

If the Citrix Agent does not start, check that corresponding keys are present in the registry.

In order to be launched during session initialization, Citrix Agent’s installer writes it to registry. For servers, it adds it under HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon, and for client machines under HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Run.

Also, make sure the Citrix agent's installation folder, usually C:\Program Files (x86)\HPE\Agent for Citrix Server, is set to "Read and Execute" and not only “Read”.

Back to top

Unexpected Disconnection

If you experience "unexpected disconnect" errors, try the following:

  • If you suspect this is due to a network issue, you can try the Citrix Session Reliability feature (this can be enabled by the Citrix administrator on the server side). When Session Reliability is enabled, Citrix Client reconnects to the server when the network connection is restored without need for user re-authentication, i.e., transparently for LoadRunner.
  • Sometimes the "unexpected disconnect" error may be caused by discrepancy of the script and server timeout settings. Consider the following scenario: The script executes some synchronization function, for example, ctrx_sync_on_window(), and waiting time is quite long, say, 180 seconds. The script does not perform any action like mouseclicks or keypresses while it is waiting for the window to appear, and the server disconnects the session when Idle Session Timeout (2 minutes by default) is exceeded. As a result, an "unexpected disconnect" message appears in the replay log. If you get "unexpected disconnect" at the synchronization step, it is recommended to check waiting time value in the script, and session timeouts on the server.

    Another workaround for unexpected disconnect at the synchronization step, is to enable User Activity Simulation - Runtime settings > Citrix > Synchronization > Enable user activity simulation. If the feature is turned on, LoadRunner will simulate user activity on a Citrix server over the specified time period and in this way prevent a disconnect.
  • It may be a result of connecting to a session that already exists on the server. When a Vuser enters an existing session, it cannot receive Windows events from a Citrix ICA object. This is a limitation of the Citrix software. To prevent this, ask the Citrix administrator to configure sessions on the Citrix server to be terminated immediately after disconnect or log off. In the VuGen script side, make sure to add a ctrx_logoff() function at the end of the script (in the vuser_end section).

    To minimize the risk of entering an existing session, Citrix Agent tries to close the session on the server when communication with the client machine is lost. This functionality is available in Citrix Agent version 12.51 and later, and enabled by default. To disable it, set LogoffSessionOnExit=0 in CtrxAgent.ini.

Back to top

Citrix Receiver—Security Warning

The Citrix client may prompt you with a warning "An online application is attempting to access files in your computer". This dialog box blocks the replay because it requires user intervention.

Workaround: To prevent this, configure the registry on the Citrix client machine to allow it to silently access local drives, as described in

Back to top

Failed to get session from client

This error occurs when the Citrix registry patch (LR\dat\Enable_Citrix_API.reg) is not installed

Workaround:Make sure the AllowSimulationAPI key is present in the above registry and not set to 0, as it enables Citrix ICO functionality. Note that in 64-bit operating systems, these keys should reside under the HKLM\Software\Wow6432Node, node, since the Citrix client is a 32-bit application.

Back to top

Citrix Error 13 "Unsupported Function"

The Citrix Error 13 is a general error code that usually refers to an error for which Citrix do not provide a specific code. This error is most common in Performance Center and BPM environments where Citrix processes (wfica32.exe, wfcrun32.exe, concentr.exe, receiver.exe…) are running in sessions other than that of the mdrv process.

Workaround: Use TaskManager or ProcessExplorer to find and kill all of these processes.

Back to top

Citrix Error 70, Client Error 1030 "Protocol driver error"

This error may occur for several reasons: network issues, proxy configuration, and so forth. Often, it occurs when you are running a Citrix+Web multi-protocol script recorded against a secured (https) Web Interface site, and the certificate required by this site is missing on the Load Generator machine.

Workaround: Try to open the published application from the Web Interface on the problematic machine. Look at the log file %APPDATA%\ICAClient\wfcwin32.log and search for “SSL Error 61”. If you find this text, it is clearly a certificate issue. For example,

09-18-2014 10:28:55:380 Calculator MUCFARMEXT01: SSL Error 61: You have not chosen to trust "AddTrust External CA Root", the issuer of the server's security certificate.

Compare certificates on the Load Generator and VuGen machines and install the missing one. Make sure that the attributes match—do not rely on a matching certificate name only. You must also check also other attributes such as “Expiration date”.

Back to top

Capturing Empty Text

In certain Windows 7 installations, VuGen is unable to capture the actual text during recording. Instead it captures empty text.


  1. Open Start > Control Panel > System and Security > System > Advanced system settings. The System Properties dialog box opens.

  2. Select the Advanced tab and click the Settings button in the Performance section.

  3. In the Performance Options dialog box, click the Visual Effects tab.

  4. Clear the check box adjacent to the last option, Use visual styles on windows and buttons.

Back to top

See also: