Citrix Director - Failure Reasons Troubleshooting Guide

book

Article ID: CTX218377

calendar_today

Updated On:

Description

Overview
User Connection Failures
Machine Failures

Overview

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.

User Connection Failures

Overview

The User Connection Failures panel of the Director console reports all failures in users’ attempts to connect to desktop/application sessions.

Failure Reasons

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.	Check in the Director console to see if the client currently has an active connection, which means no user would be currently impacted. If no session exists, review the event logs on the client and VDA for any errors. Resolve any issues with network connectivity between the client and VDA
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.	Verify that the user should have access to the application or desktop based on the user groups defined in the delivery group(s). Instruct the user to attempt to re-launch the application or desktop to determine whether this is a one-off issue. If the issue recurs, review the client device event logs for errors. Verify that the VDA to which the user is attempting to connect is registered. If unregistered, review the event logs on the VDA and resolve any issues with registration.
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.	Verify if the session was not terminated by the user before launch. Check whether any session logon procedures, such as profile load, policy processing or script execution, are taking longer than expected for users. Try relaunching the session. If the problem persists, collect CDF logs and contact Citrix support.
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.	On the controllers, verify that Active Session Reconnection is enabled via the DisableActiveSessionReconnect in the registry, by setting value to 0 under HKLM/Software/Citrix/Desktop/Server
Configuration Errors	Application Disabled	The application has been disabled by the administrator and thus cannot be accessed by end users.	Enable the relevant application and instruct the user to attempt to reconnect if the application is intended to be available for production use.
Configuration Errors	Maintenance Mode	The VDA, or the delivery group to which the VDA belongs, is set in maintenance mode.	Determine whether maintenance mode is required. Disable maintenance mode on the delivery group or machine in question if it is not needed and instruct the user to attempt to reconnect.
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.	Verify that the application or desktop is still published and that the VDAs are not in maintenance mode. Verify whether the server OS VDAs are at full load. Provision additional server OS VDAs if necessary. Verify whether there are desktop OS VDAs available for connections. Provision additional desktop OS VDAs if necessary.
Configuration Errors	Disallowed Protocol	The ICA and/or RDP protocols are not allowed.	Run the Get-BrokerAccessPolicyRule PowerShell command on a Delivery Controller and validate that the “AllowedProtocols” value has all the desired protocols listed. This should only occur in case of a misconfiguration.
Machine Failures	Spin Up Failed	VDA could not be powered-on for session launch. This is a hypervisor-reported issue.	Validate the machine is still powered off. Attempt to start the machine through Studio. Review hypervisor connectivity and permissions if this fails. If the VDA is a PVS-provisioned machine, verify the machine is up in the PVS console. If not, validate the machine is assigned a vDisk and log into hypervisor to reset the VM.
Machine Failures	No Session to Reconnect	The client attempted to reconnect to a specific session, but the session has been terminated.	Retry the workspace control reconnection
Machine Failures	Registration Timeout	The VDA was powered on, but a timeout occurred while it was attempting to register with the Controllers.	Verify that the Citrix Broker service is running on the DDC and the Desktop Service is running on the VDA. Start each if stopped. If already started, restart the Desktop Service on the VDA to restart the registration process and validate the VDA registers successfully. Confirm the DDCs configured for the VDA are accurate via the details in the Application event log. Verify the DDC and VDA can successfully communicate via ping. If not, resolve any firewall or network routing issues. Refer to the additional troubleshooting steps listed in Troubleshooting Virtual Desktop Agent Registration with Controllers in XenDesktop, as these are common problems that cause communication issues between the DDC and the VDA.
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.	Verify that the VDA is in a delivery group. If not, add it to the appropriate delivery group. Verify that the VDA shows as powered on in the Studio console. If power state is Unknown for several machines, resolve any issues with connectivity to hypervisor or host failures. Verify that the hypervisor hosting the VDA is not in maintenance mode. Restart the VDA once the above items have been addressed.
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).	Verify whether there are any VDAs in maintenance mode and disable maintenance mode if it is not needed to free up additional capacity. Consider increasing the Maximum Number of Sessions Citrix policy setting, which will allow more sessions per server VDA. Consider adding additional server OS VDAs. Consider adding more desktop OS 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.	Consider increasing Limit the number of instances running at the same time to application setting to a higher value if licensing permits.
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.	Only one instance of the application is allowed per user by design. If multiple instances per user are required, consider de-selecting the Limit to one instance per user setting in order to allow users to open more than one instance of an application.
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.	Determine whether the license server is online and reachable. Resolve any network connectivity issues to the license server and/or reboot the license server if it appears to be malfunctioning. Determine whether there are sufficient licenses in the environment and allocate more if necessary.
Unavailable Licenses	License Feature Refused	The feature being used is not covered in the existing licenses.	Contact a Citrix sales representative to verify the features that are covered by the existing XenApp/XenDesktop license edition and type.

Machine Failures

Overview

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.

Failure Reasons

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.	Escalate to hypervisor support team to review hypervisor settings
Unregistered / Failed to Start / Stuck on Boot /	Agent Shutdown	The VDA experienced a graceful shutdown	Power on the VDA if it should not be off based on existing power management policies. Review any errors in the event logs.
Unregistered / Failed to Start / Stuck on Boot /	Agent Suspended	The VDA is in hibernation or sleep mode.	Take the VDA out of hibernation mode if it should be active. Consider disabling hibernation for XenApp/XenDesktop VDA’s via power settings.
Unregistered / Failed to Start / Stuck on Boot /	Power Off	The VDA did not shut down gracefully.	If the VDA is supposed to be powered on, attempt to start the VDA within Studio and validate it boots up and registers correctly. Troubleshoot any boot or registration issues. Review the event logs on the VDA once it is back up to help determine the root cause of the shutdown. Review the hypervisor activity logs for information related to the VDA machine.
Unregistered /	Agent Address Resolution Failed	The Controller was not able to resolve the VDA’s IP address.	Verify that the VDA machine account exists in AD. If not, create it. Verify that name and IP address of the VDA machine in DNS are correct and alter if needed. If a widespread issue, validate the DNS settings on the Controller(s). Verify DNS resolution from the Controller by running the nslookup command.
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.	Upgrade the VDA if necessary Review whether the updates that were applied are supported with the 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.	Ensure the Active Directory configuration is correct, or check registry settings. This only applies if AD OU-based discovery is used for registration as described here.
Unregistered	Single Multi Session Mismatch	The VDA machine's operating system type is not compatible with the Machine Catalog or Delivery Group.	Add the VDA to the correct machine catalog type or Delivery Group containing machines with the same operating system.
Unregistered	Agent Not Contactable	A communication issue occurred between the Delivery Controller and the VDA.	Verify the DDC and VDA can successfully communicate via ping. If not, resolve any firewall or network issues. Refer to the additional troubleshooting steps listed in Troubleshooting Virtual Desktop Agent Registration with Controllers in XenDesktop, as these are common problems that cause communication issues between the DDC and the VDA.
Unregistered	Contact Lost	The Controller lost connection with the VDA. This may likely be caused by network disruptions.	Verify that the Citrix Broker service is running on the DDC and the Desktop Service is running on the VDA. Start each if stopped. If already started, restart the Desktop Service on the VDA to restart the registration process and validate the VDA registers successfully. Confirm the DDCs configured for the VDA are accurate via the details in the Application event log. Verify the DDC and VDA can successfully communicate via ping. If not, resolve any firewall or network routing issues.
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.	If this error is seen, consider adding Controllers to the site or creating a new site. Increasing the number of VDAs allowed to concurrently register with the DDC via the HKLM\Software\Citrix\DesktopServer\MaxWorkers registry key is also possible. Please see here for more details. Note that increasing this number may require additional CPU and memory resources for the DDC server.
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.	Restart the Desktop Service on the VDA to restart the registration process and validate the VDA registers correctly via the Application event log. Refer to the additional troubleshooting steps listed in Troubleshooting Virtual Desktop Agent Registration with Controllers in XenDesktop, as these are common problems that cause communication issues between the DDC and the VDA. Reinstall the VDA software if the issue is impacting all machines.
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.	Verify whether the VDA’s machine catalog functional level is lower than or equal to that of the VDA, and downgrade the machine catalog to be lower than or equal to that of the VDA if necessary.
Unregistered	Functional Level too Low for Delivery Group	The delivery group is set to a higher VDA version than the installed VDA version.	Verify whether the VDA’s delivery group functional level is lower than or equal to that of the VDA, and downgrade the delivery group to be lower than or equal to that of the VDA if necessary.
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.	Check the event logs on the Delivery Controller for any errors. Restart the Broker service if a specific issue is not evident in the logs. Once the Broker service is restarted, restart the Desktop Service on the affected VDA(s) and validate they successfully register.
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.	Verify the VDA is part of a machine catalog and delivery group. Add to the appropriate catalog and group if not a member already. In Studio, validate whether the machine is currently Registered or not and/or has an active session or not. If currently registered and (optionally) hosting a session, this error can be ignored. If the machine is unregistered, restart the Desktop Service on the VDA to force re-registration and validate in the Application event log that the VDA successfully registers. Troubleshoot any errors.
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.	Align the VDA and Controller versions. This event is unlikely to be seen if recent versions of XenApp/XenDesktop are used, as all minor versions of the XenApp 7.x platform are cross-compatible when it comes to VDA and Controller releases.
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.	If limited to a single VDA, restart the Desktop Service on the VDA to force re-registration and validate the VDA registers successfully via the Application event log. Troubleshoot any errors seen. Refer to the additional troubleshooting steps listed in Troubleshooting Virtual Desktop Agent Registration with Controllers in XenDesktop, as these are common problems that cause communication issues between the DDC and the VDA. If widespread, restart the Citrix Broker service on the Delivery Controller.
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.

Additional Resources

Director Not Updating, or Reporting Wrong Data, Data Source Unresponsive - CTX208206

Issue/Introduction

Citrix Director - Failure Reasons Troubleshooting Guide

Additional Information

Citrix Blogs - Director 7.6 Failure Reasons Demystified.

Was this article helpful?

thumb_up Yes

thumb_down No

Welcome to "KB Articles"