How do I troubleshoot issues when I install or update SSM Agent on my Amazon EC2 Windows instance?

Short description

By default, SSM Agent is preinstalled on the following Amazon Machine Images (AMI) for Windows Server:

• Windows Server 2008-2012 R2 AMIs that are published in November 2016 or later
• Windows Server 2016, 2019, and 2022

Note: The final supported version of SSM Agent for Windows Server 2008 versions is 2.3.1644.0. This operating system (OS) is no longer supported for feature or security updates from Microsoft.

Resolution

The following scenarios cause SSM Agent installation or update issues on your Amazon EC2 Windows instance:

• The OS version is unsupported.
• Windows Management Framework 3.0 or later is turned off.
• The Amazon EC2Config service isn't updated.
• The SSM Agent installation or upgrade fails with error 0x80070643.
• The SSM Agent package download fails.

The OS version is unsupported

SSM Agent isn't available for all OS versions. If you run an unsupported version of an OS, then your SSM Agent installation fails. Check the list of supported operating systems, and confirm if SSM Agent is available for your OS version. 

Windows Management Framework 3.0 or later is turned off

To run specific AWS Systems Manager documents on Windows Server instances, SSM Agent requires Windows PowerShell 3.0 or later. Make sure that your Windows Server instances are running Windows Management Framework (WMF) 3.0 or later. This framework includes Windows PowerShell. For more information, see WMF 3.0 on the Microsoft website.

The Amazon EC2Config service isn't updated

If your instance is a Windows Server 2008-2012 R2 OS that was created before November 2016, then EC2Config processes Systems Manager requests on your instance. Before you install or upgrade SSM Agent, it's a best practice to upgrade your existing instances to use the latest version of EC2Config.

The SSM Agent installation or upgrade fails with the error 0x80070643

When you install or upgrade SSM Agent, you might receive one of the following errors:

• Fatal error during installation (0x80070643)
• Failed to install MSI package

To resolve these errors, complete the following steps:

1.    Check if a previously installed SSM Agent is listed under Add or remove programs in the control panel of your Windows OS. If SSM Agent is installed, then uninstall or remove it.

2.    Rename the following SSM folders as SSM.old to create a backup or delete the folders from the directory:

• C:\Program Files\Amazon\SSM
• C:\ProgramData\Amazon\SSM

3.    If you can't view the ProgramData folder in C:\, then the folder might be hidden. Check show hidden files folder from the View tab to locate the Windows ProgramData folder.

4.    Run the regedit command, and then locate and delete the following key:

Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\AmazonSSMAgent

Note: Use the Microsoft clean-up tool to remove previous SSM Agent installations and repair corrupt registry keys. For more information, see Fix problems that block programs from being installed or removed on the Microsoft website.

5.    Reboot the server, and then manually install SSM Agent again.

6.    If you still receive errors, then review SSM Agent logs for further guidance.

The SSM Agent package download fails

When you manually install SSM Agent, the SSM Agent package is downloaded and installed from an Amazon Simple Storage Service (Amazon S3) repository. If the instance can't connect to the Amazon S3 bucket to download the package, then the SSM Agent installation fails.

To resolve this issue, make sure that your Amazon EC2 instance has access to the Amazon S3 repository to download the SSM Agent package:

• If your instance is in a private subnet with a network address translation (NAT) gateway, then see NAT gateways.
• If your instance is in a private subnet with a NAT instance, then see NAT instances.
• If your instance is in a public subnet with an internet gateway, then see Turn on internet access.
• If your instance is in a private or public subnet with an Amazon S3 virtual private cloud (VPC) endpoint, then see Gateway endpoints for Amazon S3.

The package download might also fail for the following reasons:

• The Domain Name System (DNS) servers in the OS can't resolve the Amazon S3 endpoint URLs.
• DNS resolution is deactivated for the Amazon VPC.

Related information

Automating updates to SSM Agent

How do I install AWS Systems Manager Agent (SSM Agent) on an Amazon EC2 Windows instance at launch?

Working with SSM Agent on EC2 instances for Windows Server