How do I troubleshoot a Windows WorkSpace that's in the Unhealthy state?

Short description

WorkSpaces periodically sends a health status request to each WorkSpace to check the health of the WorkSpace. If WorkSpaces doesn't receive a response from the WorkSpace, then the WorkSpace status changes to Unhealthy.

The following issues can cause the status to change to Unhealthy:

• The WorkSpace is consistently using high CPU.
• The agent or service that responds to WorkSpaces isn't running, or the management interface (ETH0) is turned off.
• An Amazon DCV or PCoIP service isn't running.
• Antivirus software is blocking WorkSpaces components.
• An application or Group Policy on the WorkSpace is blocking the network connection between WorkSpaces and the WorkSpace on the management interface.
• There are missing metadata routes.
• The WorkSpace computer name changed.

Resolution

Use CloudWatch metrics to review your WorkSpaces

To help you determine the cause, review the CPUUsage, MemoryUsage, and Unhealthy WorkSpaces metrics in Amazon CloudWatch.

Reboot the WorkSpace

Reboot the WorkSpace. If a reboot doesn't resolve the issue, then use Remote Desktop Protocol (RDP) to connect to the WorkSpace.

If you can't use RDP to connect to the WorkSpace, then see How do I troubleshoot RDP connection issues with my Amazon Elastic Cloud Compute (Amazon EC2) Windows instance? If you still can't connect to WorkSpace with RDP, then see the Restore or rebuild the WorkSpace section.

Check for high CPU

Check whether your Amazon EC2 instance has high CPU utilization. Or, use the Windows Task Manager to identify the processes that are causing high CPU.

Check that the management and customer interfaces are running

To identify the management and customer interface IP addresses, run the following command:

ipconfig /all

To show the state of the management and customer interfaces, run the following command:

netsh interface show interface

If an interface isn't in the Connected state, then run the following command to activate the interface:

netsh interface set interface "interface-name" enable

Note: Replace interface-name with your interface name.

Confirm that the WorkSpaces services are running and responsive

Use RDP to connect to the WorkSpace. Then, complete the following steps to check the service's status:

1. Choose the Start menu, and then enter Services.
2. Choose the Services tab.
3. Check each service's status for your WorkSpace.
   PCoIP WorkSpace:
   SkylightWorkSpacesConfigService
   PCoIP Standard Agent for Windows
   DCV WorkSpace:
   SkylightWorkSpacesConfigService
   WSP Adapter for DC
   DCV Server
4. If a service isn't in the Running, then open the context menu (right click) for the service. Then, choose Start.
   Note: Make sure that Start type for the service is set to Automatic.

Verify your WorkSpaces configuration

Verify that endpoint protection software, such as antivirus or anti-malware software, allows the WorkSpaces service components. If WorkSpaces Web Access is turned on for PCoIP WorkSpaces, then verify that the STXHD Hosted Application Service is Running and Start type is Automatic.

Note: If you're not using WorkSpaces Web Access, then turn off the STXHD agent.

Also, verify that an application or VPN isn't blocking your management adapter. Then, check your WorkSpace connectivity.

To check whether the Skylight certificate is in your certificate store, open certmgr.msc on your local computer. The certificate is in the Skylight folder.

To verify whether a Group Policy is blocking the communication on the management interface or a required WorkSpaces service, complete the following steps:

1. Use RDP to connect to the WorkSpace.

2. Launch Command Prompt, and then run the following command to create a policy.html file that you can open in any browser:

   gpresult /h policy.html

3. Open the policy.html document, and then search for policies that block communication to network interfaces or WorkSpaces services.

4. If you identify a blocking policy, then move the WorkSpace computer object to a separate organizational unit (OU) in Microsoft Active Directory. Use the Block inheritance setting for the object. For more information about how to use Block inheritance, see Overriding and blocking Group Policy on the Microsoft website.

5. Reboot the WorkSpace.

Verify firewall rules

The firewall must allow listed traffic on the management network interface. Also, verify that the operating system (OS) firewall or a third-party firewall has rules to allow the required ports.

Check whether the metadata routes are missing

To check whether all required metadata routes are in your WorkSpace, run the following Windows PowerShell command:

Get-NetRoute

If a metadata route is missing, then run the following script to add it to your WorkSpace:

$mgmtIp = (Get-ItemProperty "hklm:\software\Amazon\SkyLight\ConfigurationData").ManagementIp
$mgmtGW = (Get-WmiObject win32_networkAdapterConfiguration | where IPAddress -eq $mgmtIp |select DefaultIPGateway).DefaultIPGateway

if($mgmtGW){

route delete 169.254.169.123
route delete 169.254.169.249
route delete 169.254.169.250
route delete 169.254.169.251
route delete 169.254.169.252
route delete 169.254.169.253
route delete 169.254.169.254

route -P add 169.254.169.249 MASK 255.255.255.255 $mgmtGW METRIC 1000
route -P add 169.254.169.250 MASK 255.255.255.255 $mgmtGW METRIC 1000
route -P add 169.254.169.251 MASK 255.255.255.255 $mgmtGW METRIC 1000
route -P add 169.254.169.252 MASK 255.255.255.255 $mgmtGW METRIC 1000
route -P add 169.254.169.253 MASK 255.255.255.255 $mgmtGW METRIC 1000
route -P add 169.254.169.254 MASK 255.255.255.255 $mgmtGW METRIC 1000
route -P add 169.254.169.123 MASK 255.255.255.255 $mgmtGW METRIC 1000

}

After you add the missing metadata route, reboot the WorkSpace.

Verify that the computer name for the WorkSpace didn't change

Complete the following steps:

1. Open the WorkSpaces console.
2. Expand the unhealthy WorkSpace to show details.
3. Note the value for Computer name.
4. Use RDP to connect to the WorkSpace.
5. To view the current computer name, open a command prompt, and then enter hostname.
6. If the name in the output doesn't match the value for Computer name, then you must change the name back to the original name.
7. Choose Start menu, and then type sysdm.cpl.
8. Choose Change, and then enter the value for Computer name.
9. Choose OK.
10. If prompted, then enter the credential of the service AWS account that you use to join the WorkSpace to the domain.
11. Reboot the WorkSpace.

Restore or rebuild the WorkSpace

If you can't use RDP to connect to the WorkSpace, then restore the WorkSpace to roll back to the latest snapshot. If the WorkSpace is still unhealthy, then rebuild the WorkSpace.

To restore or rebuild the WorkSpace, it's a best practice to use the AWS Systems Manager AWSSupport-RecoverWorkSpace runbook.

Important: When you restore or rebuild a WorkSpace, data loss can occur. The WorkSpace is restored from the last available snapshot that's up to 12 hours old. Rebuild recreates the user volume from the most recent snapshot and the WorkSpace from the image of the bundle that you created the WorkSpace from. Applications that you installed or system settings that you changed after you created the WorkSpace are lost.

Before you run the automation, make sure that your AWS Identity and Access Management (IAM) user or role has the required permissions. For more information, see the Required IAM permissions section of AWSSupport-RecoverWorkSpace.

To run the runbook, complete the following steps:

1. Open the AWSSupport-RecoverWorkSpace runbook.
2. Choose Execute automation.
3. For the input parameters, enter the following values:
   (Optional) For AutomationAssumeRole, enter the ARN of the IAM role that allows the automation to perform actions. If you don't specify a role, then the automation uses the permissions of the user that starts the runbook.
   For Acknowledge, enter Yes to acknowledge that the Restore and Rebuild actions recover the WorkSpace from the most recent snapshot.
   For Reboot, Rebuild, or Restore, choose Yes for your preferred option.
   For WorkspaceId, enter the ID of the WorkSpace that you want to recover.
4. Choose Execute.
   For a list of the steps that the runbook performs, see the Document steps section of AWSSupport-RecoverWorkSpace.
5. Check the status of your Workspace in the Output section of the runbook.

You can also use the AWS Command Line Interface (AWS CLI) to reboot, restore, and rebuild the WorkSpace.

Note: If you receive errors when you run AWS CLI commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

If none of the preceding troubleshooting steps resolve your issue, then collect the client-side logs and open an AWS Support case.

Related information

IP address and port requirements for WorkSpaces Personal

Turn on self-service WorkSpaces management capabilities for your users in WorkSpaces Personal

How do I troubleshoot a Linux WorkSpace that's in the Unhealthy state?