Product Documentation

Troubleshoot

Mar 06, 2017

This article contains information to help administrators troubleshoot issues with Citrix Receiver for Linux. 

Connection issues

You may encounter the following connection issues.

Windows Media Player fails to play files in certain formats

Citrix Receiver may not have GStreamer plugins to handle a requested format. This normally causes the server to request a different format. Sometimes the initial check for a suitable plugin incorrectly indicates one is present. This is normally detected and causes an error dialog to appear on the server indicating that Windows Media Player encountered a problem while playing the file. Retrying the file within the session typically works because the format is rejected by Citrix Receiver, and as a result, the server will either request another format or render the media itself.

In a few situations the fact that there is no suitable plugin is not detected and the file is not played correctly, despite the progress indicator moving as expected in Windows Media Player. 

To avoid this error dialog or failure to play in future sessions:

  1. Temporarily add the configuration option "SpeedScreenMMAVerbose=On" to the [WFClient] section of $Home/.ICAClient/wfclient.ini, for example.
  2. Restart wfica from a self-service that has been started from a terminal.
  3. Play a video that generates this error.
  4. Note (in the tracing output) the mime-type associated with the missing plugin trace, or the mime-type that should be supported but does not play (for example, "video/x-h264..").
  5. Edit $ICAROOT/config/MediaStreamingConfig.tbl; on the line with the noted mime-type insert a '?' between the ':' and the mime type. This disables the format.
  6. Repeat steps 2-5 (above) for other media formats that produce this error condition.
  7. Distribute this modified MediaStreamingConfig.tbl to other machines with the same set of GStreamer plugins.
Note: Alternately, after identifying the mime-type it may be possible to install a GStreamer plugin to decode it.

I cannot connect properly to a published resource or desktop session

If, when establishing a connection to a Windows server, a dialog box appears with the message “Connecting to server…” but no subsequent connection window appears, you may need to configure the server with a Client Access License (CAL). For more information about licensing, see Licensing Your Product.

I sometimes fail to connect when I try reconnecting to sessions

Sometimes reconnecting to a session with a higher color depth than that requested by Receiver causes the connection to fail. This is due to a lack of available memory on the server. If the reconnection fails, Receiver will try to use the original color depth. Otherwise, the server will try to start a new session with the requested color depth, leaving the original session in a disconnected state. However, the second connection may also fail if there is still a lack of available memory on the server.

I cannot connect to a server using its full Internet name

Citrix recommends that you configure DNS (Domain Name Server) on your network to enable you to resolve the names of servers to which you want to connect. If you do not have DNS configured, it may not be possible to resolve the server name to an IP address. Alternatively, you can specify the server by its IP address, rather than by its name, but note that TLS connections require a fully qualified domain name, not an IP address.

I get a “Proxy detection failure” error message when connecting

If your connection is configured to use automatic proxy detection and you see a “Proxy detection failure: Javascript error” error message when trying to connect, copy the wpad.dat file into $ICAROOT/util. Run the following command, where hostname is the hostname of the server to which you are trying to connect:

cat wpad.dat | ./pacexec pac.js FindProxyForURL http://hostname hostname 2>&1 | grep “undeclared variable”

If you get no output, there is a serious issue with the wpad.dat file on the server that you need to investigate. However, if you see output such as “assignment to undeclared variable ...” you can fix the problem. Open pac.js and for each variable listed in the output, add a line at the top of the file in the following format, where “...” is the variable name.

var ...;

Sessions are very slow to start

If a session does not start until you move the mouse, there may be a problem with random number generation in the Linux kernel. To work around this, run an entropy-generating daemon such as rngd (which is hardware-based) or haveged (from Magic Software).

I want to configure a serial port setting

To configure a single serial port, add the following entries in the $ICAROOT/config/module.ini configuration file:

LastComPortNum=1 
ComPort1=<device>

To configure two or more serial ports, add the following entries in the $ICAROOT/config/module.ini configuration file:

LastComPortNum=2 
ComPort1=<device1> 
ComPort2=<device2>

Connection errors

An error dialog may appear indicating an "Error in connection: A protocol error occurred while communicating with the Authentication Service". A number of problems may cause this error condition, including:

  • When the local computer and the remote computer cannot negotiate a common TLS protocol.
  • When the remote computer requests a client certificate inappropriately. IIS should only "accept" or "require" certificates for "Citrix/Authentication/Certificate".
  • Other problems.

Display issues

Why am I seeing Screen Tearing?

Screen tearing occurs when parts of two (or more) different frames appear on the screen at the same time, in horizontal blocks. This is most visible with large areas of fast changing content on screen. Although the data is captured at the VDA in a way that avoids tearing, and the data is passed to the client in a way that doesn't introduce tearing, X11 (the Linux/Unix graphics subsystem) does not provide a consistent way to draw to the screen in a way that prevents tearing.

To prevent screen tearing, Citrix recommends the standard approach which synchronizes application drawing with the drawing of the screen; that is, wait for vsvnc, to initiate the drawing of the next frame. There are a number of options when using Linux, depending on the graphics hardware you have on the client and what window manager you are using. These options are divided into two groups of solutions:

  • X11 GPU settings
  • Use a Composition Manager
X11 GPU Configuration
For Intel HD grahics, create a file in the xorg.conf.d called 20-intel.conf with the following contents:
Section "Device"
Identifier     "Intel Graphics"
Driver          "intel"
Option         "AccelMethod" "sna"
Option         "TearFree" "true"
EndSection
 
For Nvidia graphics, locate the file in the xorg.conf.d folder that contains the "MetaModes" Option for your configuration. For each comma separated MetaMode used add the following:
{ForceFullCompositionPipeline = On}
For eample:
Option "MetaModes" "DFP-0: 1920x1200 +0+0 {ForceFullCompositionPipeline = On}"
Note: Different Linux distributions use different paths to xorg.conf.d, for example, /etc/X11/xorg.conf.d, or, /user/share/X11/xorg.conf.d.
 
Composition Managers
Use the following:
  • Compiz (built into Ubuntu Unity). You will need to install the "ComprizConfig Settings Manager."
Run "ComprizConfig Settings Manager"
Under "General->Composition", uncheck "Undirect Fullscreen Windows"
Note: "ComprizConfig Settings Manager" should be used with caution, as incorrectly changing values can prevent the system from launching.
  • Compton (an add-on utility). Refer to the man page/documentation for Compton for full details. For example, run the following command:

compton --vsync opengl --vsync -aggressive

Incorrect keystrokes appear when I use the keyboard

If you are using a non-English language keyboard, the screen display may not match the keyboard input. In this case, you should specify the keyboard type and layout that you are using. For more information about specifying keyboards, see Control keyboard behavior.

I see excessive redrawing when moving seamless windows

Some window managers continuously report the new window position when moving a window, which can result in excessive redrawing. To fix this problem, switch the window manager to a mode that draws only window outlines when moving a window.

Icon compatibility

Receiver creates window icons that work with most window managers, but are not fully compatible with the X Inter-Client Communication Convention.

To provide full icon compatibility

  1. Open the wfclient.ini configuration file.
  2. Edit the following line in the [WFClient] section: UseIconWindow=True
  3. Save and close the file.

I have cursor visibility problems

The cursor can be difficult to see if it is the same or similar in color to the background. You can fix this by forcing areas of the cursor to be black or white.

To change the color of the cursor

  1. Open the wfclient.ini configuration file.
  2. Add one of the following lines to the [WFClient] section:

    CursorStipple=ffff,ffff (to make the cursor black)

    CursorStipple=0,0 (to make the cursor white)

  3. Save and close the file.

I experience color flashing on the screen

When you move the mouse into or out of a connection window, the colors in the non-focused window may start to flash. This is a known limitation when using the X Windows System with PseudoColor displays. If possible, use a higher color depth for the affected connection.

I experience rapid color changes with TrueColor displays

Users have the option of using 256 colors when connecting to a server. This option assumes that the video hardware has palette support to enable applications to rapidly change the palate colors to produce animated displays.

TrueColor displays have no facility to emulate the ability to produce animations by rapidly changing the palette. Software emulation of this facility is expensive both in terms of time and network traffic. To reduce this cost, Receiver buffers rapid palette changes, and updates the real palette only every few seconds.

Japanese characters display incorrectly on my screen

Receiver uses EUC-JP or UTF-8 character encoding for Japanese characters, while the server uses SJIS character encoding. Receiver does not translate between these character sets. This can cause problems displaying files that are saved on the server and viewed locally, or saved locally and viewed on the server. This issue also affects Japanese characters in parameters used in extended parameter passing.

I want to make a session that spans multiple monitors

Full-screen sessions span all monitors by default, but a command-line multi-monitor display control option, -span, is also available. It allows full-screen sessions to span multiple monitors.

Desktop viewer toolbar functionality allows you to switch a session between windowed and full screen session window, including multi-monitor support for the intersected monitors. For details, see Improving user experience.

Important: -span has no effect on Seamless or normal windowed sessions (including those in maximized windows).

The - span option has the following format:

-span [h][o][a|mon1[,mon2[,mon3,mon4]]]

If h is specified, a list of monitors is printed on stdout. And if that is the whole option value, wfica then exits.

If o is specified, the session window will have the override-redirect redirect attribute.

Caution: The use of this option value is not recommended. It is intended as a last resort, for use with uncooperative window managers. The session window will not be visible to the window manager, will not have an icon and can not be restacked. It can be removed only by ending the session.

If a is specified, Receiver tries to create a session that covers all monitors.

Receiver assumes that the rest of the -span option value is a list of monitor numbers. A single value selects a specific monitor, two values select monitors at the top-left and bottom-right corners of the required area, four specify monitors at the top, bottom, left and right edges of the area.

Assuming o was not specified, wfica will use the _NET_WM_FULLSCREEN_MONITORS message to request an appropriate window layout from the window manager, if it is supported. Otherwise, it will use size and position hints to request the desired layout.

The following command can be used to test for window manager support:

xprop -root | grep _NET_WM_FULLSCREEN_MONITORS

If there is no output, there is no support. If there is no support, you may need an override-redirect window. You can set up an override-redirect window using -span o.

To make a session that spans multiple monitors from the command line:

  1. At a command prompt, type:

    /opt/Citrix/ICAClient/wfica -span h

    A list of the numbers of the monitors currently connected to the user device is printed to stdout and wfica exits.

  2. Make a note of these monitor numbers.
  3. At a command prompt, type:

    /opt/Citrix/ICAClient/wfica -span [w[,x[,y,z]]]

    where w, x, y and z are monitor numbers obtained in step 1 above and the single value w, specifies a specific monitor, two values w and x specify monitors at the top-left and bottom-right corners of the required area, and four values w, x, y and z specify monitors at the top, bottom, left and right edges of the area.

    Important: You must define the WFICA_OPTS variable before starting selfservice or connecting to the Web interface through a browser. To do this, edit your profile file, normally found at $HOME/.bash_profile or $HOME/.profile, adding a line to define the WFICA_OPTS variable. For example:
     export WFICA_OPTS="-span a"
    
    Note that this change affects both XenApp and XenDesktop sessions.
    If you have already started selfservice or storebrowse you must remove processes they started in order for the new environment variable to take effect. Remove them with:
    killall AuthManagerDaemon ServiceRecord storebrowse

I cannot escape from a full-screen session to use local applications or another session

This occurs because the client-side system UI is hidden and the Keyboard Transparency feature disables the usual keyboard command, for example Alt+Tab, sending the command to the server instead.

To work around this, use CTRL+F2 to turn off the Keyboard Transparency feature temporarily until the focus next returns to the session window. An alternative workaround is to set TransparentKeyPassthrough to No in $ICAROOT/config/module.ini. This disables the Keyboard Transparency feature, however you may have to override the ICA file by adding this setting in the All_regions.ini file.

Browser Issues

When I click on a link in a Windows session, the content appears in a local browser

Server-client content redirection is enabled in wfclient.ini. This causes a local application to run. To disable server-client content redirection, see the Setting up server-client content redirection section in Improving the user experience.

When accessing published resources, my browser prompts me to save a file

Browsers other than Firefox and Chrome may require configuration before you can connect to a published resource. If you are connecting through the Web Interface, you may be able to access the Web Interface home page with the list of resources. However, when trying to access a resource by clicking an icon on the page, your browser prompts you to save the ICA file.

To configure a different browser for use with Web Interface

Details vary among browsers, but you can set up the MIME data types in the browser so that the $ICAROOT/wfica is executed as a helper application when the browser encounters data with the application/x-ica MIME type or an .ica file.

The installer does not support a specific browser

If you have problems using a specific web browser, set the environment variable BROWSER to specify the local path and name of the required browser before running setupwfc.

When I launch desktops or applications in Firefox, nothing happens

Try enabling the ICA plug-in.

The ICA plug-in is enabled in Firefox, however desktop and application sessions are not starting

Try disabling the ICA plug-in.

Other issues

You may also encounter the following additional issues.

I want to know if the server has instructed Receiver to close a session

You can use the wfica program to log when it has received a command to terminate the session from the server. 

To record this information through the syslog system, add SyslogThreshold with the value 6 to the [WFClient] section of the configuration file. This enables the logging of messages that have a priority of LOG_INFO or  higher. The default value for SyslogThreshold is 4 (=LOG_WARNING).

Similarly, to have wfica send the information to standard error, add PrintLogThreshold with the value 6 to the [WFClient] section. The default valuefor PrintLogThreshold is 0 (=LOG_EMERG).

Refer to your operating system's documentation for instructions on configuring your syslog system.

My configuration file settings no longer work

For each entry in wfclient.ini, there must be a corresponding entry in All_Regions.ini for the setting to take effect. In addition, for each entry in the [Thinwire3.0], [ClientDrive], and [TCP/IP] sections of wfclient.ini, there must be a corresponding entry in canonicalization.ini for the setting to take effect. See the All_Regions.ini and canonicalization.ini files in the $ICAROOT/config directory for more information.

I have problems running published applications that access a serial port

If a published application needs to access a serial port, the application may fail (with or without an error message, depending on the application itself) if the port has been locked by another application. Under such circumstances, check that there are no applications that have either temporarily locked the serial port or have locked the serial port and exited without releasing it.

To overcome this problem, stop the application that is blocking the serial port; in the case of UUCP-style locks, there may be a lock file left behind after the application exits. The location of these lock files depends on the operating system used.

I cannot start Receiver

If Receiver does not start and the error message “Application default file could not be found or is out of date” appears, this may be because the environment variable ICAROOT is not defined correctly. This is a requirement if you installed Receiver to a non-default location. To overcome this problem, Citrix recommends that you do one of the following:

  • Define ICAROOT as the installation directory.

    To check the ICAROOT environment variable is defined correctly, try starting Receiver from a terminal session. If the error message still appears, it is likely that the ICAROOT environment variable is not correctly defined.

  • Reinstall Receiver to the default location. For more information about installing Receiver, see Install and set up.

    If Receiver was previously installed in the default location, remove the /opt/Citrix/ICAClient or $HOME/ICAClient/platform directory before reinstalling.

My keyboard shortcuts do not function correctly

If your window manager uses the same key combinations to provide native functionality, your key combinations might not function correctly. For example, the KDE window manager uses the combinations from CTRL+SHIFT+F1 to CTRL+SHIFT+F4 to switch between desktops 13 to 16. If you experience this problem, try the following solutions:

  • Translated mode on the keyboard maps a set of local key combinations to server-side key combinations. For example, by default in Translated mode, CTRL+SHIFT+F1 maps to the server-side key combination ALT+F1. To reconfigure this mapping to an alternative local key combination, update the following entry in the [WFClient] section of $HOME/.ICAClient/wfclient.ini. This maps the local key combination Alt+Ctrl+F1 to Alt+F1:
    • Change Hotkey1Shift=Ctrl+Shift to Hotkey1Shift=Alt+Ctrl.
  • Direct mode on the keyboard sends all key combinations directly to the server. They are not processed locally. To configure Direct mode, in the [WFClient] section of $HOME/.ICAClient/wfclient.ini, set TransparentKeyPassthrough to Remote.
  • Reconfigure the window manager so that it suppresses default keyboard combinations.

I want to enable a remote Croatian keyboard

This procedure ensures that ASCII characters are correctly sent to remote virtual desktops with Croatian keyboard layouts.

  1. In the WFClient section of the appropriate configuration file, set UseEUKSforASCII to True.
  2. Set UseEUKS to 2.

I want to find the Citrix SSLSDK or OpenSSL version number

To confirm the version number of the Citrix SSLSDK or OpenSSL that you are running, you can use the following command:
strings libctxssl.so | grep "Citrix SSLSDK"

You can also run this command on AuthManagerDaemon or PrimaryAuthManager

I want to use a Japanese keyboard on the client

To configure use of a Japanese keyboard, update the following entry in the wfclient.ini configuration file:
KeyboardLayout=Japanese (JIS)

I want to use a ABNT2 keyboard on the client

To configure use of an ABNT2 keyboard, update the following entry in the wfclient.ini configuration file:
KeyboardLayout=Brazilian (ABNT2)

Some keys on my local keyboard do not behave as expected

Choose the best-matching server layout from the list in $ICAROOT/config/module.ini.

Connection configuration errors

These errors might occur if you configured a connection entry incorrectly.

E_MISSING_INI_SECTION - Verify the configuration file: "...". The section "..." is missing in the configuration file.

The configuration file was incorrectly edited or is corrupt.

E_MISSING_INI_ENTRY - Verify the configuration file: "...". The section "..." must contain an entry "...".

The configuration file was incorrectly edited or is corrupt.

E_INI_VENDOR_RANGE - Verify the configuration file: "...". The X server vendor range "..." in the configuration file is invalid.

The X Server vendor information in the configuration file is corrupt. Contact Citrix.

wfclient.ini configuration errors

These errors might occur if you edited wfclient.ini incorrectly.

E_CANNOT_WRITE_FILE - Cannot write file: "..."

There was a problem saving the connection database; for example, no disk space.

E_CANNOT_CREATE_FILE - Cannot create file: "..."

There was a problem creating a new connection database.

E_PNAGENT_FILE_UNREADABLE - Cannot read XenApp file "...": No such file or directory.

— Or —

Cannot read XenApp file "...": Permission denied.

You are trying to access a resource through a desktop item or menu, but the XenApp file for the resource is not available. Refresh the list of published resources by selecting Application Refresh on the View menu, and try to access the resource again. If the error persists, check the properties of the desktop icon or menu item, and the XenApp file to which the icon or item refers.

PAC file errors

These errors may occur if your deployment uses proxy auto-configuration (PAC) files to specify proxy configurations.

Proxy detection failure: Improper auto-configuration URL.

An address in the browser was specified with an invalid URL type. Valid types are http:// and https://, and other types are not supported. Change the address to a valid URL type and try again.

Proxy detection failure: .PAC script HTTP download failed: Connect failed.

Check if an incorrect name or address was entered. If so, fix the address and retry. If not, the server could be down. Retry later.

Proxy detection failure: .PAC script HTTP download failed: Path not found.

The requested PAC file is not on the server. Either change this on the server, or reconfigure the browser.

Proxy detection failure: .PAC script HTTP download failed.

The connection failed while downloading the PAC file. Reconnect and try again.

Proxy detection failure: Empty auto-configuration script.

The PAC file is empty. Either change this on the server, or reconfigure the browser.

Proxy detection failure: No JavaScript support.

The PAC executable or the pac.js text file is missing. Reinstall Receiver.

Proxy detection failure: JavaScript error.

The PAC file contains invalid JavaScript. Fix the PAC file on the server. Also see Connection issues.

Proxy detection failure: Improper result from proxy auto-configuration script.

A badly formed response was received from the server. Either fix this on the server, or reconfigure the browser.

Other errors

This topic contains a list of other common error messages you may see when using Receiver.

An error occurred. The error code is 11 (E_MISSING_INI_SECTION). Please refer to the documentation. Exiting.

When running Receiver from the command line, this usually means the description given on the command line was not found in the appsrv.ini file.

E_BAD_OPTION - The option "..." is invalid.

Missing argument for option “...”.

E_BAD_ARG - The option "..." has an invalid argument: "...".

Invalid argument specified for option “...”.

E_INI_KEY_SYNTAX - The key "..." in the configuration file "..." is invalid.

The X Server vendor information in the configuration file is corrupt. Create a new configuration file.

E_INI_VALUE_SYNTAX - The value "..." in the configuration file "..." is invalid.

The X Server vendor information in the configuration file is corrupt. Create a new configuration file.

E_SERVER_NAMELOOKUP_FAILURE - Cannot connect to server "...".

The server name cannot be resolved.

Cannot write to one or more files: "...". Correct any disk full issues or permissions problems and try again..

Check for disk full issues, or permissions problems. If a problem is found and corrected, retry the operation that prompted the error message.

Server connection lost. Reconnect and try again. These files might be missing data: "...".

Reconnect and retry the operation that prompted the error.

Sending diagnostic information to Citrix Technical Support

If you are experiencing problems using Receiver, you may be asked to provide Technical Support with diagnostic information. This information assists this team in trying to diagnose the problem and offer assistance to rectify it.

To obtain diagnostic information about Receiver

  1. In the installation directory, type util/lurdump. It is recommended that you do this while a session is open and, if possible, while the issue is occurring.

    A file is generated that contains detailed diagnostic information, including version details, the contents of Receiver's configuration files, and the values of various system variables.

  2. Check the file for confidential information before sending it to Technical Support.