How do I troubleshoot a WorkSpaces Applications image builder that's stuck in Pending state?

Resolution

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

It takes up to 25 minutes for image builders and fleet instances to become available and change to a Running state. If your image builder is still in Pending state after 25 minutes, then review the following troubleshooting steps.

Elastic network interface is deleted or detached

If your elastic network interface is missing, then the image builder can't complete the start-up workflows, and the status becomes stuck in Pending state.

To check the state of your network interface, open the Amazon Elastic Compute Cloud (Amazon EC2) console. Then in the navigation pane, choose Network Interfaces.

Or, run the following command in the AWS CLI:

aws ec2 describe-network-interfaces --filters 'Name=description,Values="AppStream 2.0 - image-builder:*"'

If the network interface is missing or detached, then launch a new image builder from the last working image. Or, use a base image provided by AWS.

Note: You can check your AWS CloudTrail logs for event details associated with the network interface deletion or detachment, including eventTime and userIdentity.

PowerShell policy restrictions

If you set the PowerShell policy to Restricted before you create the image, then the image builder might become stuck in a Pending state. Also, other WorkSpaces Applications resources might fail to start. This is because the Restricted policy prevents any scripts, such as AWS Systems Manager, Sysprep, or reg key setting, from running.

To avoid this issue, use either AllSigned or RemoteSigned policies. For more information, see Use Group Policy to manage execution policy on the Microsoft website.

Applications use AppX packages

Applications that use AppX packages such as Adobe Creative Cloud might cause Sysprep to fail and image builders might get stuck in Pending state.

Before you complete the last step in the image creation process, run the following commands as an administrator in PowerShell.

To get a list of the AppX packages on the machine, run the following command:

Get-AppxPackage | select Name, PackageFullName

To remove a specific AppX package, run the following command:

Get-AppxPackage -AllUsers -Name AppXpackageName | Remove-AppxPackage -AllUsers

Note: Replace AppXpackageName with the package that you want to remove.

Important: You must run Server 2019 on the image builder. Microsoft added the -AllUsers parameter in build 1709. Server 2016 in the image builder runs on build 1607 and returns an error when you use the -AllUsers parameter.

For more information, see Get-AppxPackage on the Microsoft website.

Device drivers are conflicting or incorrect

The image builder comes pre-installed with all required drivers. If you install conflicting or incorrect drivers, then the image builder might stay in Pending state.

Because the image builder is unreachable, it's impossible to uninstall the conflicting or incorrect drivers. To fix this issue, launch a new image builder from a recent custom image, or use a base image provided by AWS.

Network interface limits

If your AWS account reaches the network interface limits for the AWS Region, then the image builder might become stuck in the Pending state. For more information about limits and how to request an increase, see Amazon VPC quotas.

Sysprep answer file customization issues

It's a best practice to not customize the Sysprep Unattend answer file. If you incorrectly customize the file, then that might interfere with the Windows start-up process and prevent the image builder from booting correctly. The process might also become stuck on the welcome screen.

To fix this issue, launch a new image builder from a recent custom image, or use a base image provided by AWS.

IPv6 is turned off

If you create an image with IPv6 turned off, then the image builder stays in Pending state. To fix this issue, launch a new image builder from a recent custom image, or use a base image provided by AWS.

Port availability

Confirm that there aren't any installed applications that use the following ports:

• Inbound TCP on port 8300, to establish the streaming connection.
• Inbound TCP on ports 8000 and 8443, for management of the streaming instance by WorkSpaces Applications.

For more information, see Management Network Interface IP Address Range and Ports in Amazon WorkSpaces Applications.

To allow access to the Amazon EC2 metadata service, you must open port 80 (HTTP) to IP address 169.254.169.254. If you configured a proxy, then you must exclude IP address 169.254.169.254 from proxy settings. For more information, see Customer Network Interface Ports in Amazon WorkSpaces Applications.

Antivirus software exceptions

Antivirus software might block the files and ports that the image builder requires. To resolve this issue, add exceptions to the following folder paths:

• %PROGRAMFILES%\Amazon\*
• %PROGRAMFILES%\NICE\*
• %PROGRAMFILES%\nodejs\*
• %PROGRAMFILES%\Internet Explorer\*
• C:\Windows\*

The preceding folder paths correspond to the following services:

• AWSLiteAgent
• AmazonSSMAgent
• Ec2Config
• PhotonAgent
• PhotonAgentWebServer (listens on port 8443)
• DcvServer (listens on port 8300)
• QWAVE

AWS CLI credentials set as system environment variables

If you set AWS CLI credentials as system environment variables, then the image builder instance might become stuck in Pending state. To prevent this issue, change system environment variables across your fleet instances.

Default language changed to an unsupported language

You can configure the default Regional settings for your WorkSpaces Applications streaming sessions, including the display language. If you change the default language to an unsupported language, then the image builder might become stuck in Pending state. To view the languages that WorkSpaces Applications currently supports, see Specify a default display language.

Deleted or renamed local administrator account

WorkSpaces Applications doesn't support renaming or deleting the local administrator account. If you rename or delete this account, the image creation fails.

For domain-joined image builders, if the local administrator account is deactivated, deleted, or renamed by Group Policy, then you can update the Group Policy object (GPO).

If the local administrator account isn't updated by GPO, then launch a new image builder from a recent custom image. Or use a base image provided by AWS.

Notification codes (Domain-joined image builders)

To see notifications, complete the following steps:

1. Open the WorkSpaces Applications console.
2. In the navigation pane, choose Images.
3. From the Image Builder tab, select your image builder.
4. Then choose the Notifications tab.

For more information, see Active Directory Domain Join.

DOMAIN_JOIN_ERROR_NO_SUCH_DOMAIN
When the image builder instance can't contact the Active Directory domain, you see the DOMAIN_JOIN_ERROR_NO_SUCH_DOMAIN error. This prevents the image builder from completing the startup workflows. To verify network connectivity, take the following actions:

• Check your VPC, subnet, and security group settings.
• Verify that the VPC DNS servers are configured correctly under the DHCP option set section of your VPC. Domain name servers are usually set to the IP addresses of the domain controllers or DNS servers responsible for your domain. For more information, see DHCP options sets in Amazon VPC.

DOMAIN_JOIN_ERROR_FILE_NOT_FOUND

When you use an invalid organizational unit (OU) distinguished name, you see the DOMAIN_JOIN_ERROR_FILE_NOT_FOUND error. You must place WorkSpaces Applications computer objects in an OU, and the distinguished name must start with OU=. For more information, see Finding the organizational unit distinguished name.

Firewall and network configuration (Domain-joined image builders)

Before you add a Directory Config object to your image builder, confirm that the firewall and network configuration are correct.

Complete the following steps:

1. Open a PowerShell window from your image builder, and then run the following commands:

   Test-NetConnection -ComputerName yourdomain.exampleco.com -Port 389 -InformationLevel "Detailed"
   Test-NetConnection -ComputerName yourdomain.exampleco.com -Port 88 -InformationLevel "Detailed"
   Test-NetConnection -ComputerName yourdomain.exampleco.com -Port 53 -InformationLevel "Detailed"

   Note: Replace yourdomain.exampleco.com with your domain name.
2. For the output of each command, verify that TcpTestSucceeded is True. When TcpTestSucceeded is True, you can reach the required ports to join the domain. For more information, see Test-NetConnection on the Microsoft website.
3. From the same PowerShell window, run the Resolve-DnsName command to confirm that you can look up the domain name:

   Resolve-DnsName -Name yourdomain.exampleco.com

   Note: Replace yourdomain.exampleco.com with your domain name.

For more information, see Resolve-DnsName on the Microsoft website.

Or, download and run the Microsoft PortQryUI tool to validate all the required ports. For more information, see PortQryUI.

New computer object not created (Domain-joined image builders)

Check Active Directory to verify whether the image builder created a new computer object in the correct OUs.

If there is a new object, then wait for the image builder instance to become available soon.

If the image builder didn't create the computer object in Active Directory, then it stays in Pending state. To troubleshoot this issue, first confirm that you granted all required service account permissions. Then, verify that the following directory configuration details in your WorkSpaces Applications Directory Config object are correct:

• Directory name (the fully qualified domain name of the directory)
• Service account user name and password
• OU distinguished name

Related information

How do I create a WorkSpaces Applications image and deploy it to my fleet?

Using Microsoft AppLocker to manage application experience on Amazon AppStream 2.0