Troubleshoot agent download and installation issues

This page has moved to You can now find all Smart Tools documentation at the Citrix Product Documentation site. Please update any page links to the new URL:

This topic provides troubleshooting tips for the following agent download and installation issues:

Unable to download the agent


Unable to download the agent. The following error message appears when you download the agent:

File not exists 


Contact Citrix Support. 

Agent installation fails [vSphere/XenServer]


Unable to install the agent on VMs in Citrix XenServer or VMware vSphere resource location. 


If agent installation fails, it can be due to firewalls blocking access to the machine. This can occur between Smart Tools and the machine or on the machine itself.

When the agent is installed on machines as part of blueprint deployment, Smart Tools uses the following inbound ports to install the agent:

  • Linux: Port 22 (SSH)
  • Windows: TCP port 3389 (RDP)

Ensure that these ports are open on the machine for successful agent installation. After the agent is installed, you can shut down these ports as all further communication between the machine and Smart Tools occurs over outbound HTTPS (port 443). 

Unable to uninstall the agent


Unable to uninstall the agent on a Windows machine.


If agent uninstallation fails on a Windows server:

  1. Ensure that the Citrix Smart Tools Agent Service is stopped. Select Start > Control Panel > System and Security > Administrative Tools > Services. From the services list, verify if the Citrix Smart Tools Agent Service is stopped. If the agent service is running, right-click Citrix Smart Tools Agent Service and select Stop.
  2. Uninstall the agent. 
  3. Delete the installation directory.

Unable to view machine details after agent registration


The agent is installed and registered successfully on a machine. However, unable to view machine details in your Smart Tools account.


This issue occurs if you have multiple Smart Tools accounts and if you download agent msi/rpm from one account, install it to a machine, and try to view machine details on a different account. The machine details appear only on the account from which the agent is downloaded. 

To resolve this issue, perform the following tasks:

  1. Uninstall the agent from the machine
  2. Delete the installation directory
  3. Download the correct agent msi/rpm (agent that belongs to a specific account)
  4. Install the agent on the machine
    The machine details appear on the Smart Tools account from where you downloaded the agent msi/rpm.

Agent installation times out


Unable to install agent on a machine. Agent installation comes to a stand still and times out.


This issue occurs if the VM template (in XenServer or vSphere) is not created as per the standard guidelines. For more information on how to prepare VM templates on different resource locations, see Prepare Windows Server VM templates for deploying blueprints

Agent installation fails for non-admin users having administrator privileges on Windows


During blueprint deployment, agent installation fails for non-admin users having administrator privileges on a Windows machine. The following error message appears in the blueprint deployment step output:

Failed to install agent


Before you create a Windows VM template, ensure that you have disabled User Access Control on Windows. Deploy your blueprint using the Windows VM template. The agent installation is successful.