Tips and Troubleshooting Guide
Tips
-
If your first installation failed or you have an older VDA but you like to enroll it towards a new DDC, invoke “sudo /opt/Citrix/VDA/bin/vdaconfig” to re-open the vdaconfig tool UI to perform corresponding actions.
-
Regarding the performance testing under a high-latency network Env, we can do the following to get a better result.
-
Change the FPS target from the default value of 30 to 15.
-
Change to Full-screen H264 and give a test. (The fonts on the desktop may look slightly blurry, but the performance will be improved. It is a tradeoff between quality and performance).
-
Change the rate limit from the default of 30 to 20 (it only works to FullScreen H264 and Selective H264)
-
-
Check out blogs.citrix.com or KB articles for more tips and tweaks for performance etc
Advanced troubleshooting steps for Administrator
Use DaaS/CVAD admin console to recover macOS VDA session services
Use these recovery steps when an end user cannot connect to a remote Mac VDA from Citrix Workspace app, or when the session connects but the desktop appears black or gray.
Always complete Step 1 first. If the session can connect but the desktop remains black or gray after Step 1, continue to Step 2.
-
Step 1: Restart the Mac VDA Session Components
Use this step first when either of the following issues occurs:
-
The end user cannot launch or reconnect to a remote session from Citrix Workspace app.
-
The session connects, but the desktop appears black or gray in Citrix Viewer.
Administrator can try restarting the Mac VDA session components from Citrix DaaS Monitor or CVAD Director.
-
In Citrix DaaS Monitor or CVAD Director, locate the Mac VDA machine currently used by the affected end user.
-
Open the machine’s process page.
Find the following processes:
/opt/Citrix/VDA/bin/ctxhdx/usr/local/share/dotnet/dotnet/opt/Citrix/VDA/lib/BrokerAgentMac.dll -
Select each process and choose End process.
-
Wait for the VDA to register again.
-
Ask the end user to try connecting again.
-
-
Step 2: Restart Display-Related Processes if the Desktop Is Still Black or Gray
Use this step only if Step 1 does not resolve the issue, the user can connect to the session, and the desktop is still black or gray in Citrix Viewer. If you need to proceed to this step, it indicates that relevant desktop service issues are affecting the session display and that the macOS desktop services must be restarted. In this recovery flow, replayd is a per-user process, and WindowServer is a per-system process.
-
Go back to the machine’s process page in Citrix DaaS Monitor or CVAD Director.
-
Find the following process:
/usr/libexec/replayd -
Select the process and choose End process.
-
Ask the end user to reconnect to the session.
-
If the user still sees a black or gray desktop after reconnecting, go back to the machine’s process page and find the following process:
/System/Library/PrivateFrameworks/SkyLight.framework/Resources/WindowServer -daemon -
Select the process and choose End process.
-
Ask the end user to reconnect again.
-
Warning:
Ending the WindowServer process closes the applications currently open in the user session, and unsaved data may be lost.
Note:
This is a recovery workaround for stuck sessions or display components.
Ending these processes interrupts the current user session.
Always complete Step 1 before using Step 2.
Wait until the Mac VDA is fully registered again before asking the user to reconnect.
If the issue occurs repeatedly, collect diagnostic logs and contact Citrix support.
Blank screen enhancements (Release 2511 onwards)
For the new MacVDA release, instead of presenting users with a black screen when the graphics module fails to work, the system will now display an informational screen that guides users through self-service troubleshooting for graphics issues. This feature helps resolve most common graphics problems, including screen recording permission issues, invalid display resolution configurations, and system-level issues that prevent the graphics module from functioning properly.
No Screen Recording Permission
This is a common issue faced by customers deploying macVDA for the first time or as a result of accidental misconfiguration during daily use. When this issue occurs, an error info image will be displayed to guide the customer, as shown in the example below.
Invalid Display Resolution
This issue arises when customers resize the Citrix Workspace App (CWA) window to a size that is either too small or too large, exceeding the supported resolution range of macOS. In such cases, an error info image will be displayed to inform the customer, as shown in the example below.
Fatal Error in System Service
Although rare, this issue occurs when a critical system service fails, leaving the system unable to recover easily. When this happens, an error info image will be displayed to notify the customer and provide guidance, as shown in the example below.
Troubleshooting Guide
While you deploy and use Citrix VDA for macOS, you may face some problems. Here are some common issues that you may encounter.
The CWA (Citrix Workspace™ App) cannot launch the session to my remote macOS device
To launch a session successfully, your Citrix VDA must be enrolled and correctly configured in the Citrix Web Studio. Log in to the Citrix Web Studio and check the following items.
-
Make sure that the machine is shown as Registered.
-
Assign the user with a machine in the delivery group settings.
I can connect but the CWA is showing a gray screen
Check whether the Screen Recording privacy setting is enabled for Citrix Graphics Service.
I cannot hear or record any voice from my CWA side
Make sure that your audio input and output is using Citrix Audio Device.
I cannot enter the text
Make sure the Accessibility permission is assigned to the Citrix Input Service.
For easy troubleshooting on how to enable remote desktop and remote login to VDA machine, Refer
- Remote desktop https://support.apple.com/en-sg/guide/mac-help/mh11851/mac
- Remote login https://support.apple.com/en-sg/guide/mac-help/mchlp1066/mac
What information should I collect if the problem persists?
Seek Citrix team help and gather below information as much as you can, before that if possible, you can also run hdxmonitorlite.sh or XDPing.sh (refer to: https://docs.citrix.com/en-us/mac-vda/configure/administration/tools-and-utilities) for leads of diagnostics:
(M: mandatory field O: optional field)
[M] Issue Description:
[M] Critical issue impact session usage: (Yes) or (No)
[M] Citrix Workspace app (CWA) type and version
[M] Issue happened in: (DaaS) or (CVAD) or (both)
[M] Session launch from: (Citrix Gateway Service) or (StoreFront/Netscaler)
[O] Issue reproducible: (Yes) or (No)
[O] Screenshots or screen captures (if any):
[M] VDA side system information and logs: Please run the following command and all information is packaged as a single file. Please attach this file when you report any issues.
$ sudo /opt/Citrix/VDA/bin/xdlcollect.sh
In addition, also include the output (includes the session information, such as the protocols and connection details) of the following command if possible:
$ /opt/Citrix/VDA/bin/ctxsession -v > ctxsession.out.txt