Citrix Troubleshoot Connection
The Citrix Troubleshoot Connection feature is designed to empower end-users to effectively self-troubleshoot potential desktop or application launch failures. This enhancement aims to provide users with clear diagnostics, potential recommendations, and the ability to run fixes with a simple click.
Overview
Citrix now delivers more granular and enhanced error messages to help users clearly understand the root cause of launch failures. The Troubleshoot Connection feature performs real-time analysis of reachability challenges to the Virtual Delivery Agent (VDA) during the launch process. It then presents user-friendly error messages and recommendations, enabling users to either resolve the issue directly or gather logs for a support ticket if needed.
Connection paths analyzed
The feature diagnoses potential virtual app and desktop launch issues across critical connection points, including:
- Network connectivity from the Client to the Gateway.
- Gateway to StoreFront server connection.
- StoreFront server to Broker connection.
- Broker to VDA connection.
Enhanced error messages and diagnostics
In the event of launch failures, Citrix now displays clear, user-friendly error messages that pinpoint specific connection issues, such as network errors, server unavailability, or VDA failures. For administrators, detailed error codes are provided in the logs, categorized into server-side and client-side errors, serving as valuable references for deeper investigation.
Self-recovery and remediation actions
The Citrix Troubleshoot Connection feature includes steps that users can take to automatically recover from common issues, thereby minimizing the need for support intervention. Following are the potential problems that can be resolved with guided remediation:
- Restart VDA
- Restart Citrix Workspace app (CWA) - Re-Login to CWA
- Refresh the resource list
- Refresh the app and try
- Reconfigure the store
- Upgrade CWA
- Reinstall CWA
- Check the network
- Wait And retry
System requirements
To use the Troubleshoot Connection feature, have the following Citrix Workspace app versions:
- Citrix Workspace app for Mac: Version 2505 and later
- Citrix Workspace app for Windows: Version 2507 and later
- Citrix Workspace app for iOS: Version 2509 and later
- Citrix Workspace app for Android: Version 2509 and later
How to use
The Troubleshoot Connection feature is enabled by default for Citrix DaaS environments. Granular and enhanced error messages, along with remediation recommendations, are provided for both browser-launched sessions and sessions launched directly through the native Citrix Workspace app.
Important considerations
While the feature offers robust self-service capabilities, it’s important to note the following:
- The “Restart VDA” remediation action does not support sessions launched through a hybrid launch mode (that is, downloading an ICA file from a browser and then launching it with the native Citrix Workspace app).
Error codes
The error codes are split between server side errors and client side errors. Following are the tables with error codes.
Common server-side errors
| Error ID | Description | Recommendation |
|---|---|---|
ResourceNotFound |
The resource was removed by your administrator. | For an up-to-date list of available apps and desktops, either refresh Citrix Workspace app or log out and back in. |
WorkstationInMaintenance |
The desktop is under planned maintenance. | Wait until the maintenance is complete, then try again. |
UnavailableDesktop |
There are no desktops available to connect to. | Wait a few minutes, then try again. If the issue persists, contact your system administrator. |
UnavailableAppProtectedDesktop |
App Protection required to open protected resources. | Upgrade to a Citrix Workspace app version with App Protection, or contact your system administrator for assistance. |
NotLicensed |
Unable to launch the resource because the server is missing the appropriate license. | Contact your system administrator for assistance. |
NoMoreActiveSessions |
Unable to launch the resource because there are no available session slots. | Wait a few minutes, then try again. If the issue persists, contact your system administrator. |
GeneralAppLaunchError |
An unknown error occurred while trying to open the resource. | Contact your system administrator for assistance. |
ResourceDisabled |
Your administrator has disabled the resource. | For an up-to-date list of available apps and desktops, either refresh Citrix Workspace app or log out and back in. |
Citrix Workspace app for Windows
| Error ID | Description | Recommendation |
|---|---|---|
CertificateError |
An error occurred with the server certificate. | Contact your system administrator for assistance. |
PassthroughClientError |
There is already an active session. | Contact your system administrator for assistance. |
IcaFileRetrieveError |
An error occurred while trying to retrieve the ICA file. | Contact your system administrator for assistance. |
Icafileretrieveerrorreconnection |
An error occurred while trying to retrieve the ICA file during reconnection. | Contact your system administrator for assistance. |
NoCWA |
Citrix Workspace app required to open resources. | Install Citrix Workspace app or contact your system administrator for assistance. |
CouldNotFindStore |
Unable to retrieve the required store configuration to launch the resource. | Remove the store from Citrix Workspace, then add it again. If the issue persists, contact your system administrator. |
noclientinstalled |
Unable to retrieve the required information to launch the resource. | Refresh Citrix Workspace app or log out and back in. |
AuthCancelled |
The authentication session expired. | To try to resolve the issue, reauthenticate in Citrix Workspace. If the issue persists, contact your system administrator. |
IcaFileLaunchError |
An error occurred while trying to start the ICA file. | Quit and reopen Citrix Workspace. If the issue persists, contact your system administrator. |
CouldNotContactStore |
An error occurred while trying to communicate with the VDA. This might be due to a server connection issue. | Quit and reopen Citrix Workspace. If the issue persists, contact your system administrator. |
CCMError |
Unable to launch the resource due to a Connection Manager error. Error code: {errorCodeValue} | Quit and reopen Citrix Workspace. If the issue persists, contact your system administrator. |
CCMInitFailed |
Unable to launch the resource because the Connection Manager failed to initialize. | Quit and reopen Citrix Workspace. If the issue persists, contact your system administrator. |
CCMLoadFailed |
Unable to launch the resource because the Connection Manager failed to load. | Quit and reopen Citrix Workspace. If the issue persists, contact your system administrator. |
InvalidIcaParams |
Unable to launch the resource due to incorrect ICA parameters. | Quit and reopen Citrix Workspace. If the issue persists, contact your system administrator. |
AppExiting |
Unable to launch the resource because the Citrix Workspace app is exiting. | Quit and reopen Citrix Workspace. If the issue persists, contact your system administrator. |
UTF8ConversionFailed |
Unable to parse the ICA file. | Quit and reopen Citrix Workspace. If the issue persists, contact your system administrator. |
MissingSoftware |
You need additional software to use this app. | Contact your system administrator for assistance. |
Citrix Workspace app for Mac
| Error ID | Description | Recommendation |
|---|---|---|
AuthCancelled |
The authentication session expired. | To try to resolve the issue, first authenticate with your credentials. If the issue persists, contact your system administrator. |
NetworkError |
Unable to launch the resource due to a network connection issue. | Check your connection and try again. If the issue persists, contact your system administrator. |
ViewerNotFound |
The Citrix Viewer path cannot be found. | To try to resolve the issue, uninstall and reinstall Citrix Workspace. If the issue persists, contact your system administrator. |
ViewerOpenEventFailed |
Citrix Viewer failed to create an event. | Try to launch the resource from your store again. If the issue persists, contact your system administrator. |
ViewerLaunchTimeout |
Citrix Viewer launch timed out. | Try to launch the resource from your store again. If the issue persists, contact your system administrator. |
ViewerLaunchFailure |
Citrix Viewer failed to launch. | Try to launch the resource from your store again. If the issue persists, contact your system administrator. |
InvalidICAFile |
Unable to launch the resource because the ICA file is invalid. | Try to launch the resource from your store again. If the issue persists, contact your system administrator. |
CertificateError |
An error occurred with the server certificate. | Contact your system administrator for assistance. |
ResourceError |
An error occurred while trying to start the resource. This might be due to a server connection issue. | Wait a few minutes, then try again. If the issue persists, contact your system administrator. |
UnknownError |
An unknown error occurred while trying to open the resource. | Wait a few minutes, then try again. If the issue persists, contact your system administrator. |
Citrix Workspace app for iOS
| Error ID | Description | Recommendation |
|---|---|---|
credentialsMustChange |
Your password must be changed. | Go to your account settings to change your password. If the issue persists, contact your system administrator. |
noConfigurationFile |
Unable to retrieve the required configuration data. | To try to resolve the issue, remove the store from Citrix Workspace, then add it again. If the issue persists, contact your system administrator. |
http404Error |
Resources are unavailable. | Contact your system administrator for assistance. |
invalidTransactionId |
Invalid transaction ID. | Wait a few minutes, then try again. If the issue persists, contact your system administrator. |
credentialsExpired |
Your password expired. | Go to your account settings to change your password. If the issue persists, contact your system administrator. |
badAddressError |
Unable to find the resource address. | Check your connection and try again. If the issue persists, contact your system administrator. |
accountDisabled |
Your account is disabled. | Contact your system administrator for assistance. |
accountLockedOut |
Your account is temporarily locked. | Contact your system administrator for assistance. |
storeServerConnectionError |
An error occurred while trying to communicate with the server. | Wait a few minutes, then try again. If the issue persists, contact your system administrator. |
internalServerError |
An unknown error occurred while trying to connect to the server. | Contact your system administrator for assistance. |
invalidXML |
Unable to open the resource due to an error from the XML service. | Contact your system administrator for assistance. |
badCredentials |
Your credentials expired. | To try to resolve the issue, log out of Citrix Workspace and then log back in. If the issue persists, contact your system administrator. |
appRemoved |
Resource was removed or disabled by your administrator. | For an up-to-date list of available apps and desktops, either refresh Citrix Workspace app or log out and back in. |
invalidLogonHours |
Unable to log in at this time due to restrictions set by your administrator. | Try again during regular working hours. If the issue persists, contact your system administrator. |
connectionError |
Unable to connect to the server. This can be due to a network connection issue. | To try to resolve the issue, quit and reopen Citrix Workspace. If the issue persists, contact your system administrator. |
Citrix Workspace app for Android
| Error ID | Description | Recommendation |
|---|---|---|
http404Error |
Unable to launch the resource due to a network connection issue. | Check your connection and try again. If the issue persists, contact your system administrator. |
couldNotConnectToWorkstation |
Unable to connect to the desktop. | Quit and reopen Citrix Workspace. If the issue persists, contact your system administrator. |
retryReasonRebooting |
An error occurred while launching resource. The requested workstation is rebooting. | Quit and reopen Citrix Workspace. If the issue persists, contact your system administrator. |
retryReasonResuming |
An error occurred while launching resource. The requested workstation is resuming. | Quit and reopen Citrix Workspace. If the issue persists, contact your system administrator. |
generalProblem |
Something went wrong while trying to open the resource. | Quit and reopen Citrix Workspace. If the issue persists, contact your system administrator. |
retryReasonUnknown |
An error occurred in the ICA file. | Quit and reopen Citrix Workspace. If the issue persists, contact your system administrator. |
appRemoved |
The resource was removed or disabled by your administrator. | For an up-to-date list of available apps and desktops, either refresh the Citrix Workspace app or log out and log in. |
resourceError |
An error occurred while trying to start the ICA file. | Wait a few minutes, then try again. If the issue persists, contact your system administrator. Restart VDA if it’s a dedicated machine. |
resourceUnavailable |
An error occurred while trying to start the ICA file. | Wait a few minutes, then try again. If the issue persists, contact your system administrator. Restart VDA if it’s a dedicated machine. |
Citrix Troubleshoot Connection
Copied!
Failed!