Citrix Director is a comprehensive monitoring and troubleshooting tool that integrates with XenApp and XenDesktop environments. The solution provides a single pane of glass for Citrix support and administrator teams to gain insight into environment health and performance metrics. This in turn allows administrators to better discover issues before they impact users, as well as troubleshoot issues when end users experience them.
This document focuses on detailing the failure reasons that are displayed in the Director console under the umbrella categories of User Connection Failures, Failed Desktop OS Machines, and Failed Server OS Machines. Failure reasons help the administrator to more efficiently troubleshoot issues by identifying one of the many possible causes of an issue, which can serve as the starting point for troubleshooting.
The sections in this document summarize each failure reason, define the meanings of these failures, and list action items that serve as a starting point for troubleshooting and resolving issues. Please note that this document is not comprehensive of all possible causes of issues that occur within a XenApp/XenDesktop environment, and that the troubleshooting steps are intended to be a starting point for the issue resolution process. Some failures will share the same action items as they are specific examples of the same general root cause, such as VDA communication failure to the Delivery Controllers.
The User Connection Failures panel of the Director console reports all failures in users’ attempts to connect to desktop/application sessions.
The table below provides details and troubleshooting steps for each User Connection related failure reason.
Failure Type | Failure Reason | Description | Actions |
---|---|---|---|
Client Connection Failures | Connection Timeout | The client did not connect to the VDA after the VDA was prepared for session launch. The session was successfully brokered, but a timeout occurred while waiting for the client to connect to the VDA. This could be caused by issues that prevent the client from effectively connecting to the VDA, such as firewall settings, network interruptions, or settings that prevent remote connections. |
|
Client Connection Failures | Ticketing | Failure occurred during ticketing, indicating that the client connection to the VDA does not match the brokered request. A launch request ticket is prepared by the broker and delivered in the ICA file. When the user attempts to launch a session, the VDA will validate the launch ticket in the ICA file with the broker. A failure can occur if ICA file corruption occurs or if a user is attempting to make an unauthorized connection. |
|
Client Connection Failures | Logon Timeout | A session has been reported as terminated from the VDA after the client has initially contacted the VDA but before it completed the logon sequence. |
|
Client Connection Failures | Active Session Reconnect Disabled | The specific application or desktop session that the user attempted to launch is active and connected to a different endpoint. However, the user’s current endpoint is unable to connect to the active session. |
|
Configuration Errors | Application Disabled | The application has been disabled by the administrator and thus cannot be accessed by end users. |
|
Configuration Errors | Maintenance Mode | The VDA, or the delivery group to which the VDA belongs, is set in maintenance mode. |
|
Configuration Errors | Resource Unavailable | The application or desktop to which the user is attempting to connect is not available. This application or desktop may no longer exist, or there are no VDAs available to run it. This can be caused if the application or desktop has since been unpublished, or if the VDAs hosting the application or desktop have reached maximum load or are set in maintenance mode. |
|
Configuration Errors | Disallowed Protocol | The ICA and/or RDP protocols are not allowed. |
|
Machine Failures | Spin Up Failed | VDA could not be powered-on for session launch. This is a hypervisor-reported issue. |
|
Machine Failures | No Session to Reconnect | The client attempted to reconnect to a specific session, but the session has been terminated. |
|
Machine Failures | Registration Timeout | The VDA was powered on, but a timeout occurred while it was attempting to register with the Controllers. |
|
Machine Failures | Communication Error | The Controller attempted to send information to the VDA, such as a request to prepare for a connection, but an error occurred in the communication attempt. This may be caused by network disruptions. | |
Machine Failures | Refused | The Controller sends a request to the VDA to prepare for a connection from an end user, but the VDA actively refuses this request. | |
Machine Failures | Session Preparation | Session prepare request from the Controller to the VDA failed. This may be caused by communication issues between the Controller and the VDA, issues experienced by the Broker service while creating a prepare request, or the VDA’s inability to accept the request due to reasons such as network issues. | |
Machine Failures | Configuration Set Failure | The Controller failed to send required configuration data, such as policy settings and session information, to VDA during session launch. This may be caused by communication issues between the Controller and the VDA, issues experienced by the Broker service while creating a configuration set request, or the VDA’s inability to accept the request due to reasons such as network issues. | |
Machine Failures | Machine Not Functional | The VDA is not functional. Some causes of this failure include: the VDA was removed from the delivery group, the VDA is unregistered, the VDA power state is unavailable, or the VDA is experiencing internal issues. |
|
Unavailable Capacity | Session Limit Reached | All VDAs are in use and there is no capacity to host additional sessions. This may occur if all VDAs are in use (for desktop OS VDAs), or all VDAs have reached the configured maximum concurrent sessions allowed (for server VDAs). |
|
Unavailable Capacity | Max Concurrent Instances Exceeded | The maximum number of instances of an application has been reached. No additional instances of the application can be open on the VDA. This issue is generally related to the application limits feature. |
|
Unavailable Capacity | Max Instances Per User Exceeded | The user is attempting to open more than one instance of an application, but the application is configured to allow only a single instance of the application per user. This issue is generally related to the applications limits feature. |
|
Unavailable Licenses | Licensing | The licensing request failed. This could be caused by issues such as insufficient number of licenses, or the license server has been down for more than 30 days. |
|
Unavailable Licenses | License Feature Refused | The feature being used is not covered in the existing licenses. |
|
The Failed Desktop OS Machines and Failed Server OS Machines panels of the Director console report machines that are in a failed state, along with a reason for the failure. The Failed Desktop OS Machines and Failed Server OS Machines panels report failures in the VDAs themselves. This differs from the User Connection Failures panel described in the previous section, which reports failures in the attempts to start a connection to the VDA.
The table below provides details and troubleshooting steps for each Machine (server and desktop OS VDA) related failure reason.
Failure Type | Failure Reason | Description | Action |
---|---|---|---|
Unregistered / Failed to Start / Stuck on Boot / Maximum Load | Hypervisor Reported Failure | The hypervisor reported an error. |
|
Unregistered / Failed to Start / Stuck on Boot / | Agent Shutdown | The VDA experienced a graceful shutdown |
|
Unregistered / Failed to Start / Stuck on Boot / | Agent Suspended | The VDA is in hibernation or sleep mode. |
|
Unregistered / Failed to Start / Stuck on Boot / | Power Off | The VDA did not shut down gracefully. |
|
Unregistered / | Agent Address Resolution Failed | The Controller was not able to resolve the VDA’s IP address. |
|
Unregistered | Agent Rejected Settings Update | Settings, such as Citrix policies, were changed or updated but there was an error in sending the updates to the VDA. This may occur if the updates are incompatible with the installed VDA version. |
|
Unregistered | Agent Wrong Active Directory OU | An Active Directory discovery misconfiguration occurred. The site-specific OU (where the site controller information is stored in AD) configured in the VDA registry is for a different site. |
|
Unregistered | Single Multi Session Mismatch | The VDA machine's operating system type is not compatible with the Machine Catalog or Delivery Group. |
|
Unregistered | Agent Not Contactable | A communication issue occurred between the Delivery Controller and the VDA. |
|
Unregistered | Contact Lost | The Controller lost connection with the VDA. This may likely be caused by network disruptions. |
|
Unregistered | Broker Registration Limit Reached | The DDC has reached the configured maximum number of VDA’s that are allowed to concurrently register to it. By default, the DDC allows 10,000 concurrent VDA registrations. |
|
Unregistered | Empty Registration Request | The registration request sent from the VDA to the DDC was empty. This may be due to a corrupt VDA software installation. |
|
Unregistered | Invalid Registration Request | The VDA made a registration request to the broker, but the content of the registration request is corrupt or invalid. | |
Unregistered | Missing Agent Version | When registering with the broker, the VDA reports its Citrix Broker Protocol version to the DDC. This failure reason appears if the VDA fails to communicate the Citrix Broker Protocol version. | |
Unregistered | Missing Registration Capabilities | The VDA version not compatible with the Delivery Controller. | |
Unregistered | Functional Level too Low for Catalog | The machine catalog is set to a higher VDA version than the installed VDA version. |
|
Unregistered | Functional Level too Low for Delivery Group | The delivery group is set to a higher VDA version than the installed VDA version. |
|
Unregistered | Settings Creation Failure | The Broker failed to construct a set of settings and configurations to send to the VDA. As part of the hard registration process, the Broker gathers and sends settings and configurations to the VDA. If the Broker is unable to gather the data, hard registration fails and the VDA becomes deregistered. |
|
Unregistered | Soft Registered | The VDA software has been installed and configured to point to the Delivery Controllers, but it is not yet fully configured. This is usually caused by the machine not being part of a machine catalog and delivery group. |
|
Unregistered | Hard Registration Pending | The VDA is not yet fully set up for hosting sessions. The machine experienced issues while transitioning from a soft registered state to a hard registered state. | |
Unregistered | Incompatible Version | The VDA cannot communicate with the Controller due to a mismatch in the Citrix protocol versions. This is due to incompatibility between the VDA and Controller versions. |
|
Unregistered | Inconsistent Registration Capabilities | The VDA cannot communicate its capabilities with the Broker. This may be due to incompatibility between the VDA and Controller versions. The registration capabilities, which change with each version, are expressed in a form that does not match the registration request. | |
Unregistered | Unsupported Credential Security Version | The VDA and DDC are not using the same encryption mechanism. | |
Unregistered / Maximum Load | Send Settings Failure | The Broker failed to send settings and configuration data to the VDA. As part of the hard registration process, the Broker gathers and sends settings and configurations to the VDA. If the Broker is able to gather the data, but is unable to send it, hard registration fails and this failure reason results. |
|
Unregistered / Maximum Load | Session Prepare Failure | The Broker failed to notify the VDA to prepare to host a session. When a user requests a connection to a VDA and the VDA is hard registered, the broker notifies the VDA to prepare to be contacted by a receiver instance. If the call fails, the VDA is forcibly deregistered, resulting in this failure. | |
Unregistered / Maximum Load | Session Audit Failure | The broker failed to complete an audit of the sessions that are running on the VDA. |
Citrix Blogs - Director 7.6 Failure Reasons Demystified.