Product Documentation

Troubleshoot blueprint deployment issues

Important: This topic has been deprecated and will be removed. For more information about deprecated features and functions in Smart Tools, see What’s New in Citrix Smart Tools.

This topic provides troubleshooting tips for blueprint deployment issues.

Download XenDesktop ISO step fails or takes more time

During a XenDesktop blueprint deployment, the Download XenDesktop ISO step fails or takes more time to complete.

To resolve this issues, Contact Citrix support.

Note: If you want to deploy XenDesktop Blueprint multiple times, you can host the XenDesktop ISO on your local web server or CIFS share. This reduces the download time and likelihood of step failure.

Machine creation fails due to unavailability of Elastic IP (Amazon EC2)

The following error message is displayed in the step output after blueprint deployment:

elastic ip: The maximum number of addresses has been reached.

Smart Tools requires at least one Elastic IP in Amazon EC2. By default, AWS accounts are allowed up to 5 Elastic IP addresses. To resolve this issue, make sure you haven’t reached the 5-address limit for your account.

To release an Elastic IP:

  1. Log on to your Amazon Web Services console.
  2. In the AWS Dashboard, click EC2.
  3. In the EC2 Dashboard, under NETWORK & SECURITY, click Elastic IPs.
  4. Right-click the address and select Release Addresses.

Machine creation fails due to disabled subscription

During blueprint deployment, Smart Tools can’t create a machine in a Microsoft Azure Classic or Amazon EC2 resource location. The following error message appears:

The subscription is in a disabled state.

To resolve this issue, ensure that your Microsoft Azure or Amazon EC2 account subscription is up-to-date and enabled.

Deployment fails due to unavailability of subnet for NAT instance (Amazon EC2)

Smart Tools can’t deploy a blueprint in an Amazon EC2 resource location because there is no available subnet for the NAT instance. When this issue occurs, Smart Tools displays the following error message:

Can't find a free subnet for nat instance.

To resolve this issue, you need to create a VPC with required subnets. You can do one of the following to create a VPC with both public and private subnets:

  • Use the VM configuration wizard in Smart Tools to create a new VPC.
  • Use the Create VPC Wizard in the Amazon EC2 console.

Deployment fails due to duplicate DNS name (Microsoft Azure Classic)

Smart Tools fails to deploy a blueprint and displays the following error message:

The specified DNS name is already taken.

All the services in Azure Classic share the same domain, .cloudapp.net or .websites.net. Another user might be using the same DNS name. To avoid this issue, use a unique DNS name.

Smart Tools is unable to communicate with the machine that acts as a connector

Blueprint deployment fails because Smart Tools is unable to communicate with the machine that acts a connector. The following error message appears in the VM configuration wizard:

Failed creating scalex gate tunnel, error: Failed executing gate command

The error message indicates that the machine that acts a connector is offline. Ensure that the machine is powered on and connected to the network.

Unable to deploy a blueprint as the host machine is down

Blueprint deployment fails with the following error message:

The machine that acts as a connector is unable to communicate with the host machine (Host IP).

The error message indicates that the machine acting as a connector is unable to communicate with the host machine. Ensure that the host machine is powered on and connected to the network.

Unable to deploy a blueprint to a VM

Blueprint deployment fails with the following error message:

Smart Tools is unable to communicate with the machine (*IP_Address*). Ensure the machine is up and running

The error message indicates that the VM is halted or shut down and you cannot deploy a blueprint or script. If the script is deployed on an offline node, the IP address is not displayed. Ensure that the machine is powered on and connected to the network.

Unable to deploy a blueprint due to insufficient memory on the hypervisor (XenServer)

Blueprint deployment fails with the following error message:

XenAPI error: HOST_NOT_ENOUGH_FREE_MEMORY

The error message indicates that there is insufficient memory on the hypervisor to provision a VM and deploy a blueprint.

To resolve this issue, you can:

  • Stop or delete unused VMs
  • Increase the memory on the hypervisor

Unable to deploy a blueprint due to insufficient storage on the hypervisor

Blueprint deployment fails with the following error message:

SR_BACKEND_FAILURE_44 There is insufficient space

The error message indicates that there is insufficient space on the hypervisor to provision a VM and deploy a blueprint.

To resolve this issue, you can:

  • Stop or delete unused VMs
  • Increase the storage space on the hypervisor

Unable to deploy a blueprint using an existing deployment profile

During blueprint deployment, if you select an already existing deployment profile the following error message appears:

Invalid deployment profile. The resource location associated with this profile is unavailable.

The error message indicates that the resource location used in the selected deployment profile no longer exists. Deploy the blueprint using another deployment profile or without a deployment profile. If you do not use a deployment profile, you can save your current deployment as a new profile and use that in your future deployments.

Reboot step fails during blueprint deployment

During blueprint deployment, the Reboot step fails after running for a long time with the following error message:

Server with agentId:*agent_ID* was shutdown successfully but failed to restart. Machine reboot wait time expired

The reboot failure may be because of server failure during shutdown. The reboot might have taken long time because of creation of failure dump or logs. Server failure can occur due to problems including faulty hypervisor, bad sector on the disk, or corrupted OS image.

If your blueprint is configured to pause on failure and you want to manually rerun the failed Reboot step, you can try the following steps:

  • Login to your hypervisor or host and check the status of the VM.
  • Verify the notifications or alerts displayed in the hypervisor or host.
  • Manually restart or reboot the VM.
  • If the problem persists, deploy the blueprint again.

Agent installation fails on an Amazon EC2 provisioned VM

During blueprint deployment, Smart Tools agent installation fails on an Amazon EC2 provisioned VM.

Verify if there is a status check failure for the VM instance on your AWS console:

  1. Logon to your Amazon Web Services console.
  2. In the AWS Dashboard, click EC2.
  3. In the EC2 Dashboard, under INSTANCES, click Instances.
  4. Click the VM instance on which agent installation is failed. The instance details are displayed below the instances list.
  5. Click the Status Checks tab to view status check messages or errors.
  6. In case of status check failures, contact AWS support to investigate further on the problem.

    Status Checks tab in AWS console

For more information on AWS Instance Status Checks and Troubleshooting, see the following AWS documentation:

If the problem persists after issue resolution by Amazon, contact Citrix Technical Support.

Reboot step fails on an Amazon EC2 provisioned VM

During blueprint deployment, Reboot step fails on an Amazon EC2 provisioned VM .

The reboot failure may be because of server failure during shutdown. The reboot might have taken long time because of creation of failure dump or logs. Server failure can occur due to problems including faulty hypervisor, bad sector on the disk, or corrupted OS image.

Verify if there is a status check failure for the VM instance on your AWS console:

  1. Logon to your Amazon Web Services console.
  2. In the AWS Dashboard, click EC2.
  3. In the EC2 Dashboard, under INSTANCES, click Instances.
  4. Click the VM instance on which agent installation is failed. The instance details are displayed below the instances list.
  5. Click the Status Checks tab to view status check messages or errors.
  6. In case of status check failures, contact AWS support to investigate further on the problem.

    Status Checks tab in AWS console

For more information on AWS Instance Status Checks and Troubleshooting, see the following AWS documentation:

Contact Citrix Support, if the problem persists after issue resolution by Amazon.

Where to find additional help

If you need additional help resolving an issue with deploying a blueprint, you can contact Citrix Technical Support.

When contacting Support, be sure to provide the following information:

  • The Smart Tools account name you are using to deploy the blueprint.
  • The deployment name.
  • The URL of the deployment report. Click Manage > Details and then copy the URL of the Deployment Details page.
  • The agent log file from the machine involved in the issue. For more information, see the “Share debug log files with Citrix Support” section of Connectivity requirements.