Troubleshooting Common Issues

• VM deploys successfully, but doesn’t appear in Machine Catalog
• Desktop is not visible in Citrix Workspace
• VDA logs show registration errors

• Check VDA service status

    ansible mac_vms -i inventory \
      -m shell \
      -a "sudo launchctl list | grep citrix"

• Verify network connectivity

    ansible mac_vms -i inventory \
      -m shell \
      -a "curl -v https://[customer_ID].xendesktop.net 2>&1 | grep Connected"

• Review VDA logs

    ansible mac_vms -i inventory \
      -m shell \
      -a "sudo tail -100 /Library/Application\ Support/Citrix/VDA/Logs/vda.log"

• Restart VDA service

    ansible mac_vms -i inventory \
      -m shell \
      -a "sudo launchctl kickstart -k system/com.citrix.vda"

• Expired enrollment token
• Firewall blocking TCP 443 to *.xendesktop.net
• Incorrect ID in VDA configuration
• DNS resolution failure
• VDA service crashed during startup

Issue: Session fails to launch or times out

• Desktop appears in Citrix Workspace, but fails to launch/won’t launch
• Connection progress bar stalls at a certain percentage
• “Unable to connect” error message is displayed

• Verify VM is powered on

    ansible-playbook -i inventory list_orka_vms.yml

• Check Citrix Cloud console

* Machine state should be “Registered” and “Available”

* Machine state should not be “Unregistered”, “Maintenance”, or “In Use”

• Test Rendezvous connectivity (if using)

    ansible mac_vms -i inventory \
      -m shell \
      -a "curl -v https://*.*.nssvc.net 2>&1 | grep Connected"

• Verify HDX ports are open

* Client → VM: TCP 1494, TCP 2598, UDP 1494, UDP 2598

* Test with 
      
      nc -zv <vm-ip> 1494

• Check client side for issues

* Update Citrix Workspace app to the latest version

* Clear Citrix Workspace app cache

* Try different client devices to help identify the problem

* If available, test from a different network to rule out network restrictions

• VM powered ‘Off’, or crashed
• Rendezvous connection broken (check Gateway Service availability)
• Firewall is blocking HDX ports
• Network routing issues
• Citrix Workspace application is out-of-date

Issue: Poor session performance or lag

• High input lag when typing, moving the mouse, or gesturing using the trackpad
• Low frame rate, choppy display
• Applications slow to respond
• Video playback stutters

• Check host resource utilization

    ansible hosts -i inventory \
      -m shell \
      -a "top -l 1 | grep 'CPU usage'"

• Check VM resource allocation

* Ensure VM has adequate CPU/RAM allocated

* Compare allocation to baseline requirements to ensure minimums are met

• Check network latency with

    ping <vm-ip>

* Test bandwidth availability

* Check for packet loss

• Review HDX policies

* Check Citrix policies for codec settings

* Verify compression settings are appropriate for the connection

* Ensure adaptive transport is enabled

• Application specific issues

* Some applications may not perform well over HDX

* Check Citrix compatibility for specific software

* Consider GPU acceleration needs, if any

• Insufficient VM resources
• Host oversubscribed (too many VMs)
• High network latency or packet loss
• Suboptimal HDX policies for connection type
• Graphics-intensive applications without GPU support

Issue: Clipboard or file transfer not working

• Cannot copy/paste between the client and the VM
• File drag-and-drop fails
• Error messages when attempting clipboard operations

• Check HDX policies in Citrix Cloud

* Navigate to Policies → HDX Settings

* Verify that “Client clipboard redirection” is enabled

* Verify that “Client drive redirection” is enabled

• Restart the session

* Log out and back in (sometimes, policies don’t apply until a new session has been started)

• Update Citrix Workspace application

* Ensure the latest version is installed, as older versions may have bugs when using the Clipboard

• Test with different types of content

* Try plain text first

* Then try formatted text, images, or files

* Isolate what’s working vs. what’s not working

• HDX policy is blocking the clipboard/file transfer
• Security policy is restricting file transfers
• Citrix Workspace application has a bug (updating may resolve this)
• Content size exceeds limits

Issue: VM fails to deploy or gets stuck during deployment

• Ansible playbook times out during VM creation
• VM is created, but never boots up
• VM boots, but services don’t start

• Check Orka Engine status

    ansible hosts -i inventory \
      -m shell \
      -a "orka-engine --version"

• Verify the image exists and is valid

ansible hosts -i inventory \
  -m shell \
  -a "orka-engine image list"

• Check available disk space

ansible hosts -i inventory \
  -m shell \
  -a "df -h /var/orka"

• Review Orka logs

ansible hosts -i inventory \
  -m shell \
  -a "sudo tail -100 /var/log/orka-engine.log"

• Attempt to manually deploy

* SSH to Orka host

* Manually run
      
      orka-engine vm create

* Observe error messages

• Force VM shutdown if VM is still stuck

ansible-playbook -i inventory stop_orka_vm.yml \
  -e "vm_name=stuck-vm" \
  -e "force=true"

• Insufficient disk space for VM creation
• Corrupted image
• Host resource exhaustion
• Network bridge misconfiguration
• Apple 2-VM licensing limit reached on host

Issue: Image operations fail

• Image pull from container registry fails or times out
• Image backup/commit fails
• Publishing an image to container registry fails

• Test registry connectivity

    ansible hosts -i inventory \
      -m shell \
      -a "curl -v https://registry.example.com"

• Verify registry credentials

* Check Ansible Vault contains correct credentials

* Test authentication manually

• Check available disk space

    ansible hosts -i inventory \
      -m shell \
      -a "df -h /var/orka"

• Review image size

* Images larger than 20GB may timeout on slow networks

* Consider optimizing images as needed

• Test with a smaller image

    ansible-playbook -i inventory pull_orka_image.yml \
      -e "remote_image=ghcr.io/macstadium/orka-images/sonoma:latest" \
      -e "local_name=test-pull"

• Network timeout (large image + slow connection)
• Registry authentication failure
• Insufficient disk space
• Registry rate limiting
• Corrupted image layers

​

Troubleshooting best practices

1. Start with simple tests, then move on to more complex diagnostics
2. Check one layer at a time (network → host → VM → VDA → Citrix)
3. Use verbose output when running playbooks for debugging

     ansible-playbook -i inventory <playbook.yml> -vvv

4. Test on a single host before assuming an issue is widespread

     ansible-playbook -i inventory <playbook.yml> --limit mac-node-1

5. Document resolutions to issues for future reference, and add them to your internal company troubleshooting documentation
6. Monitor logs proactively, and set up alerts as needed