How can I troubleshoot an AppStream 2.0 image builder that is stuck in Pending status?

Last updated: 2020-06-30

When I try to launch an Amazon AppStream 2.0 image builder, the status stays in Pending state and doesn’t change to Running. How do I fix this? 

Resolution

It can take 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, consult the following common causes and troubleshooting steps.

Elastic network interface is deleted or detached

A missing network interface can prevent the image builder from completing the startup workflows, leaving the status stuck in Pending state.

To verify the state of your network interface, open the Amazon Elastic Compute Cloud (Amazon EC2) console, and then choose Network Interfaces from the navigation pane. Or, to use the AWS Command Line Interface (AWS CLI), enter the following command:

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

If the network interface is missing or detached, launch a new image builder from the last working image or from 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.

Device drivers are conflicting or incorrect

The image builder comes pre-installed with all required drivers. The image builder might stay in Pending status if a user installs conflicting or incorrect drivers.

Because the image builder is unreachable, it isn’t possible to uninstall the conflicting or incorrect drivers. To fix this issue, launch a new image builder from a recent custom image, or using one of the Amazon-provided base images.

Network interface limits

Your Amazon Web Services (AWS) account might have reached the network interface limits for the Region. 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. Incorrect customization can interfere with the Windows startup process by preventing the image builder from booting correctly and getting stuck on the welcome screen.

To fix this issue, launch a new image builder from a recent custom image, or using one of the Amazon-provided base images.

IPv6 is disabled

If you create an image with IPv6 disabled, the image builder will stay in Pending status. To fix this issue, launch a new image builder from a recent custom image, or using one of the Amazon-provided base images.

Base image compatibility

Verify that you aren’t launching a new Graphics Pro (NVIDIA) image builder using a Graphics Design (AMD) base image, or vice versa. For more information, see AppStream 2.0 base image version history.

Port availability

Confirm that there aren’t any installed applications using 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 AppStream 2.0.

For more information, see Management network interface IP address range and ports.

Antivirus software exceptions

Antivirus software can block the files and ports that the image builder requires. Consider adding exceptions to the following folder paths:

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

The above folder paths correspond to the following services:

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

AWS Command Line Interface (AWS CLI) credentials as system environment variables

Setting AWS CLI credentials as system environment variables might prevent AppStream 2.0 from creating the image. For instructions to change system environment variables across your fleet instances, see Change system environment variables.

Default language changed to an unsupported language

You can configure the default regional settings for your AppStream 2.0 streaming sessions, including the display language. An image builder will get stuck in Pending if you change the default language to an unsupported language. To view the languages that AppStream 2.0 currently supports, see Specify a default display language.

Notification codes (Domain-joined image builders)

To see notifications, open the AppStream 2.0 console, and then choose Images from the navigation pane. From the Image Builder tab, select your image builder, and then choose the Notifications tab. For more information, see Troubleshooting notification codes.

  • DOMAIN_JOIN_ERROR_NO_SUCH_DOMAIN
    The image builder instance isn’t able to contact the Active Directory domain. This prevents the image builder from completing the startup workflows. To ensure network connectivity, confirm 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 generally set to the IP addresses of the domain controllers or DNS servers responsible for your domain. For more information, see DHCP options sets.
  • DOMAIN_JOIN_ERROR_FILE_NOT_FOUND
    The organizational unit (OU) distinguished name is invalid. AppStream 2.0 computer objects must be placed in an organizational unit, 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 adding a Directory Config object to your image builder using the AppStream 2.0 console, confirm that the firewall and network configuration are correct. Follow these 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"

2.    For the output of each command, verify that TcpTestSucceeded is True. This indicates that you can reach the required ports to join the domain. For more information, see Test-NetConnection.

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

Or, download and run the Microsoft PortQryUI tool to validate all the required ports.

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

In Active Directory, verify whether a new computer object was created in the correct organizational units (OUs).

If there is a new object, the image builder instance will be available soon.

If the computer object doesn’t get created, the image builder stays in Pending state. To troubleshoot this issue, first confirm that all required service account permissions are granted. Then, verify that the following directory configuration details in your AppStream 2.0 Directory Config object are correct:

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

Did this article help you?

Anything we could improve?


Need more help?