Citrix Director failure reasons and troubleshooting
The following tables describe the various failure categories, the reasons, and the action you need to take to resolve the issues. For more information, see Enums, error codes, and descriptions.
Connection failure errors
| Category | Reason | Issue | Action |
|---|---|---|---|
| N/A | [0] Unknown. This error code is not mapped. | The Monitoring service cannot determine the reason for the reported launch or connection failure from information shared by the Brokering service. | Collect CDF logs on the controller and contact Citrix support. |
| [0] None | [1] None | None | N/A |
| [2] MachineFailure | [2] SessionPreparation | Session preparation request from the delivery controller to the VDA failed. Possible causes: Communication issues between the controller and the VDA, issues experienced by the Broker Service while creating a prepare request, or network issues resulting in the VDA not accepting the request. | Refer to troubleshooting steps listed in Knowledge center article, Troubleshooting Virtual Delivery Agent Registration with delivery controllers in Citrix Virtual Apps and Desktops for common problems that cause communication issues between the controller and the VDA. |
| [2] MachineFailure | [3] RegistrationTimeout | The VDA was powered on, but a time-out occurred while it was attempting to register with the delivery controller. | Verify that the Citrix Broker Service is running on the delivery controller and that the Desktop service is running on the VDA. Start each if stopped. |
| [1] ClientConnectionFailure | [4] ConnectionTimeout | The client did not connect to the VDA after the VDA was prepared for session launch. The session was successfully brokered, but a time-out occurred while waiting for the client to connect to the VDA. Possible causes: Firewall settings, network interruptions, or settings that prevent remote connections. | Check the Director console to see if the client currently has an active connection, which means no user is impacted. If no session exists, review the event logs on the client and on the VDA for any errors. Resolve any issues with network connectivity between the client and the VDA. |
| [4] NoLicensesAvailable | [5] Licensing | The licensing request failed. Possible causes: Insufficient number of licenses, or the license server has been down for more than 30 days. | Verify that the license server is online and reachable. Resolve any network connectivity issues to the license server or reboot the license server if it appears to be malfunctioning. Verify that there are sufficient licenses in the environment and allocate more if necessary. |
| [1] ClientConnectionFailure | [6] Ticketing | A 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 validates the launch ticket in the ICA file with the Broker. Possible causes: ICA file is corrupt or the user is attempting to make an unauthorized connection. | Verify that the user has access to the application or desktop based on user groups defined in the delivery groups. Instruct the user to relaunch the application or desktop to determine whether this is a one off issue. If the issue occurs again, 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 registration issues. |
| [1] ClientConnectionFailure | [7] Other | A session has been reported as terminated from the VDA after the client has initially contacted the VDA but before it completed the connection sequence. | Verify if the session was not terminated by the user before launch. Try relaunching the session, if the problem persists, collect CDF logs and contact Citrix support. |
| [1] ClientConnectionFailure | [8] GeneralFail | The session failed to launch. Possible causes: A brokered launch was requested while the broker was still starting up or initializing, or internal error during the brokering phase of a launch. | Verify that the Citrix Broker Service is running and retry launching the session. |
| [5] Configuration | [9] MaintenanceMode | 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. |
| [5] Configuration | [10] ApplicationDisabled | The application cannot be accessed by end users because it has been disabled by the administrator. | If the application is intended to be available for production use, enable the application and instruct the user to reconnect. |
| [4] NoLicensesAvailable | [11] LicenseFeature Refused | The feature being used is not covered by the existing licenses. | Contact a Citrix sales representative to confirm the features that are covered by the existing Citrix Virtual Apps and Desktops license edition and type. |
| [3] NoCapacityAvailable | [13] SessionLimitReached | All VDAs are in use and there is no capacity to host more sessions. Possible causes: All VDAs are in use (for single-session OS VDAs), or all VDAs have reached the configured maximum concurrent sessions allowed (for multi-session OS VDAs). | Verify if there are any VDAs in maintenance mode. Disable maintenance mode if it is not needed to free up more capacity. Consider increasing the value of Maximum Number of Sessions in the Citrix policy setting to allow more sessions per server VDA. Consider adding more multi-session OS VDAs. Consider adding more single-session OS VDAs. |
| [5] Configuration | [14] DisallowedProtocol | The ICA and RDP protocols are not allowed. | Run the Get-BrokerAccessPolicyRule PowerShell command on the delivery controller and verify that the AllowedProtocols value has all the desired protocols listed. This issue occurs only if there is a misconfiguration. |
| [5] Configuration | [15] ResourceUnavailable | The application or desktop to which the user is attempting to connect is not available. This application or desktop might not exist, or there are no VDAs available to run it. Possible causes: The application or desktop has been unpublished, or the VDAs hosting the application or desktop have reached maximum load, or the application or desktop is set in maintenance mode. | Verify that the application or desktop is still published and the VDAs are not in maintenance mode. Determine whether the multi-session OS VDAs are at full load. If so, provision more multi-session OS VDAs. Verify that there are single-session OS VDAs available for connections. Provision more single-session OS VDAs if necessary. |
| [5] Configuration | [16] ActiveSessionReconnectDisabled | The ICA session is active and connected to a different endpoint. However, because the Active Session Reconnection is disabled, the client cannot connect to the active session. | On the delivery controller, verify that Active Session Reconnection is enabled. Verify that the value of DisableActiveSessionReconnect in the registry, under HKEY_LOCAL_MACHINE\Software\Citrix\Desktop\Server is set to 0. |
| [2] MachineFailure | [17] NoSessionToReconnect | The client attempted to reconnect to a specific session but the session was terminated. | Retry the workspace control reconnection. |
| [2] MachineFailure | [18] SpinUpFailed | The VDA cannot be powered on for session launch. This is a hypervisor reported issue. | If the machine is still powered off, attempt to start the machine from Citrix Studio. If this fails, review the hypervisor connectivity and permissions. If the VDA is a PVS-provisioned machine, verify in the PVS console that the machine is running. If not, verify that the machine is assigned a Personal vDisk, log in to the hypervisor to reset the VM. |
| [2] MachineFailure | [19] Refused | The delivery controller sends a request to the VDA to prepare for a connection from an end user, but the VDA actively refuses this request. | Verify via ping, that the delivery controller and the VDA can successfully communicate. If not, resolve any firewall or network routing issues. |
| [2] MachineFailure | [20] ConfigurationSet Failure | The delivery controller did not send required configuration data, such as policy settings and session information, to the VDA during session launch. Possible causes: Communication issues between the controller and the VDA, issues experienced by the Broker Service while creating a configuration set request, or network issues resulting in the VDA not accepting the request. | - |
| [3] NoCapacityAvailable | [21] MaxTotalInstancesExceeded | The maximum number of instances of an application has been reached. No additional instances of the application can be opened on the VDA. This issue is related to the application limits feature. | Consider increasing the application setting, Limit the number of instances running at the same time to a higher value if licensing permits. |
| [3] NoCapacityAvailable | [22] MaxPerUserInstancesExceeded | 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 related to the application limits feature. | Only one instance of the application is allowed per user by default. If multiple instances per user are required, consider clearing the Limit to one instance per user setting in the application setting. |
| [1] ClientConnectionFailure | [23] Communication error | The delivery controller attempted to send information to the VDA, such as a request to prepare for a connection, but an error occurred during the communication attempt. This can be caused due to network disruptions. | If already started, restart the Desktop service on the VDA to restart the registration process and verify that the VDA registers successfully. Confirm that the delivery controllers configured for the VDA are accurate via the details in the application event log. |
| [3] NoCapacityAvailable | [100] NoMachineAvailable Monitoring service converts [12] NoDesktopAvailable to this error code. | The VDA assigned to launch the session is in an invalid state or is unavailable. Possible causes: Power state of the VDA is unknown or unavailable, the VDA did not reboot since the last user’s session, session sharing is disabled while the current session requires it to be enabled, or the VDA was removed from the delivery group or from the site. | Verify that the VDA is in a delivery group. If not, add it to the appropriate delivery group. Verify that there are sufficient VDAs registered and in ready state to be able to launch the published shared desktop or application requested by the user. Verify that the hypervisor hosting the VDA is not in maintenance mode. |
| [2] MachineFailure | [101] MachineNotFunctional. Monitoring service converts [12] NoDesktopAvailable to this error code. | The VDA is not operational. Possible causes: 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 Citrix Studio. If the power state is unknown for several machines, resolve any issues with connectivity to the hypervisor or host failures. Verify that the hypervisor hosting the VDA is not in maintenance mode. Restart the VDA once these issues have been addressed. |
Machine failure type
| Error Code | Error Code ID | Issue | Action |
|---|---|---|---|
| Unknown | - | - | - |
| Unregistered | 3 | - | - |
| MaxCapacity (represented as Max Load on Director) | 4 | Machine is reporting itself at maximum capacity i.e. Max Load Index | Ensure that all hypervisors are powered on. Add more machines to the affected Delivery Groups by adding more capacity to the hypervisor or by adding more hypervisors. |
| StuckOnBoot | 2 | The VM did not complete its boot sequence and is not communicating with the hypervisor. | Ensure that the VM booted successfully on the hypervisor. Check for other messages on the VM, such as OS issues. Ensure that the hypervisor tools are installed on the VM. Ensure that the VDA is installed on the VM. |
| FailedToStart | 1 | The VM experienced issues when trying to start on the hypervisor. | Check the hypervisor logs. |
| None | 0 | - | - |
Machine deregistration reason (applicable when failure type is Unregistered or Unknown)
| Error Code | Error Code ID | Issue | Action |
|---|---|---|---|
| AgentShutdown | 0 | The VDA experienced a graceful shutdown. | Power on the VDA if you do not expect it to be off based on existing power management policies. Review any errors in the event logs. |
| AgentSuspended | 1 | The VDA is in hibernation or sleep mode. | Take the VDA out of hibernation mode. Consider disabling hibernation for Citrix Virtual Apps and Desktops VDAs via power settings. |
| IncompatibleVersion | 100 | The VDA cannot communicate with the delivery controller due to a mismatch in the Citrix protocol versions. | Align the VDA and delivery controller versions. |
| AgentAddressResolutionFailed | 101 | The delivery 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 the name and the IP address of the VDA in DNS are accurate. If not, correct them. If widespread, validate the DNS settings on the delivery controllers. Verify DNS resolution from the controller by running the nslookup command. |
| 101 | The delivery 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 the name and the IP address of the VDA in DNS are accurate. If not, correct them. | |
| AgentNotContactable | 102 | A communication issue occurred between the delivery controller and the VDA. | Use a ping to verify that the delivery controller and the VDA can successfully communicate. If not, resolve any firewall or network issues. Refer to the troubleshooting steps listed in Knowledge Center article, Troubleshooting Virtual Delivery Agent Registration with delivery controllers in Citrix Virtual Apps and Desktops (CTX136668), for common problems that cause communication issues between the controller and the VDA. |
| 102 | A communication issue occurred between the delivery controller and the VDA. | Refer to troubleshooting steps listed in Knowledge Center article, Troubleshooting Virtual Delivery Agent Registration with delivery controllers in Citrix Virtual Apps and Desktops (CTX136668), for common problems that cause communication issues between the controller and the VDA. Contact Citrix support. | |
| AgentWrongActiveDirectoryOU | 103 | An Active Directory discovery misconfiguration occurred. The site-specific OU (where the site controller info 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. |
| EmptyRegistrationRequest | 104 | The registration request sent from the VDA to the delivery controller was empty. This can be due to a corrupt VDA software installation. | Restart the Desktop service on the VDA to restart the registration process and verify that the VDA registers correctly via the application event log. |
| MissingRegistrationCapabilities | 105 | The VDA version is not compatible with the delivery controller. | Upgrade the VDA or remove the VDA and then reinstall it. |
| MissingAgentVersion | 106 | The VDA version is not compatible with the delivery controller. | Reinstall the VDA software if the issue is impacting all machines. |
| InconsistentRegistrationCapabilities | 107 | The VDA cannot communicate its capabilities to the Broker. This can be due to incompatibility between the VDA and delivery controller versions. The registration capabilities, which change with each version, are expressed in a form that does not match the registration request. | Align the VDA and delivery controller versions. |
| NotLicensedForFeature | 108 | The feature you are attempting to use is not licensed. | Check your Citrix licensing edition, or remove the VDA and then reinstall it. |
| 108 | The feature you are attempting to use is not licensed. | Contact Citrix support. | |
| UnsupportedCredentialSecurity version | 109 | The VDA and the delivery controller are not using the same encryption mechanism. | Align the VDA and delivery controller versions. |
| InvalidRegistrationRequest | 110 | The VDA made a registration request to the Broker but the content of the request is corrupt or invalid. | Refer to the troubleshooting steps listed in Knowledge Center article, Troubleshooting Virtual Delivery Agent Registration with delivery controllers in Citrix Virtual Apps and Desktops (CTX136668), for common problems that cause communication issues between the controller and the VDA. |
| SingleMultiSessionMismatch | 111 | The VDA’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. |
| FunctionalLevelTooLowForCatalog | 112 | The machine catalog is set to a higher VDA functional level than the installed VDA version. | Verify that the VDA’s machine catalog functional level matches that of the VDA. Upgrade or downgrade the machine catalog to match that of the VDA. |
| FunctionalLevelTooLowForDesktopGroup | 113 | The delivery group is set to a higher VDA functional level than the installed VDA version. | Verify that the VDA’s delivery group functional level matches that of the VDA. Upgrade or downgrade the machine catalog to match that of the VDA. |
| PowerOff | 200 | The VDA did not shut down gracefully. | If the VDA is supposed to be powered on, attempt to start the VDA from Citrix Studio and verify that 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. |
| AgentRejectedSettingsUpdate | 203 | Settings such as Citrix policies were changed or updated but there was an error in sending the updates to the VDA. This can 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. |
| SessionPrepareFailure | 206 | The Broker did not complete an audit of the sessions that are running on the VDA. | If widespread, restart the Citrix Broker Service on the delivery controller. |
| 206 | The Broker did not complete an audit of the sessions that are running on the VDA. | Contact Citrix support. | |
| ContactLost | 207 | The delivery controller lost connection with the VDA. This can be caused by network disruptions. | Verify that the Citrix Broker Service is running on the delivery controller 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 verify that the VDA registers successfully. Confirm that the delivery controllers configured for the VDA are accurate via the details in the Application event log. Use a ping to verify that the delivery controller and the VDA can successfully communicate. If not, resolve any firewall or network issues. |
| 207 | The delivery controller lost connection with the VDA. This can be caused by network disruptions. | Verify that the Desktop service is running on the VDA. Start if stopped. | |
| BrokerRegistrationLimitReached | 301 | The delivery controller has reached the configured maximum number of VDAs that are allowed to concurrently register with it. By default, the delivery controller allows 10,000 concurrent VDA registrations. | Consider adding delivery controllers to the Site or creating a Site. You can also increase the number of VDAs allowed to concurrently register with the delivery controller via the HKEY_LOCAL_MACHINE\Software\Citrix\DesktopServer\MaxWorkers registry key. See Knowledge Center article, Registry Key Entries Used by Citrix Virtual Apps and Desktops (CTX117446) for more information. Increasing this number might require more CPU and memory resources for the controller. |
| SettingsCreationFailure | 208 | The Broker did not construct a set of settings and configurations to send to the VDA. If the Broker is unable to gather the data, registration fails and the VDA becomes unregistered. | 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 VDAs and verify that they successfully register. |
| 208 | The Broker did not construct a set of settings and configurations to send to the VDA. If the Broker is unable to gather the data, registration fails and the VDA becomes unregistered. | Restart the Desktop service on the affected VDAs and verify that they successfully register. Contact Citrix support. | |
| SendSettingsFailure | 204 | The Broker did not send settings and configuration data to the VDA. If the Broker can gather the data but is unable to send it, registration fails. | If limited to a single VDA, restart the Desktop service on the VDA to force reregistration and validate that the VDA registers successfully via the application event log. Troubleshoot any errors seen. Refer to the troubleshooting steps listed in Knowledge center article, Troubleshooting Virtual Delivery Agent Registration with delivery controllers in Citrix Virtual Apps and Desktops (CTX136668), for common problems that cause communication issues between the controller and the VDA. |
| AgentRequested | 2 | An unknown error occurred. | Contact Citrix support. |
| DesktopRestart | 201 | An unknown error occurred. | Contact Citrix support. |
| DesktopRemoved | 202 | An unknown error occurred. | Contact Citrix support. |
| SessionAuditFailure | 205 | An unknown error occurred. | Contact Citrix support. |
| UnknownError | 300 | An unknown error occurred. | Contact Citrix support. |
| RegistrationStateMismatch | 302 | An unknown error occurred. | Contact Citrix support. |
| Unknown | - | An unknown error occurred. | Contact Citrix support. |
Citrix Director failure reasons and troubleshooting
Copied!
Failed!