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 2016, 2019, 2022 (except for Nano versions), and 2025
• Windows Server 2008-2012 R2 AMIs published in November 2016 or later
  Note: Windows Server 2012 and 2012 R2 reached end of support on October 10, 2023. It's a best practice not to use these operating system (OS) versions. To use SSM Agent with these versions, it's a best practice to use Extended Security Updates (ESUs) from Microsoft. For more information, see Windows Server 2012 and 2012 R2 reaching end of support on the Microsoft website.

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

Note: It's a best practice to check the status of SSM Agent before you use Systems Manager on an Amazon EC2 instance for the first time. For instructions, see Verify the status of SSM Agent.

Resolution

Prerequisite: Before you install SSM Agent, check that your OS supports Systems Manager and that you set up Systems Manager correctly.

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

• The SSM Agent package download fails.
• You deactivated Windows Management Framework 3.0 or later.
• The Amazon EC2Config service isn't updated.
• The SSM Agent installation or upgrade fails with error 0x80070643.
• Antivirus or other security software might interfere with SSM Agent during installation or updates and network communication. 

Troubleshoot package download failures

When you manually install SSM Agent, the SSM Agent package downloads and installs from its Amazon Simple Storage Service (Amazon S3) bucket. If the instance can't connect to the Amazon S3 bucket to download the package, then the SSM Agent installation fails.

Review the following resources based on your configuration, and verify that your instance has access to the S3 bucket that contains 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 Internet gateway basics.
• If your instance is in a private or public subnet with an Amazon Virtual Private Cloud (Amazon VPC) endpoint, then see Gateway endpoints for Amazon S3.

Package downloads also fail for the following reasons:

• The DNS servers in the OS can't resolve the Amazon S3 endpoint URLs.
• You deactivated the DNS resolution for your Amazon VPC.

Activate Windows Management Framework 3.0 or newer

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

Update the Amazon EC2Config service

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

Troubleshoot "Fatal error during installation" 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 exists under Add or remove programs in the control panel of your Windows OS. If you previously installed SSM Agent, then uninstall or remove it.

2. Delete the following SSM folders or rename the folders to maintain them as backups:
   C:\Program Files\Amazon\SSM
   C:\ProgramData\Amazon\SSM

   Note: If you can't view the ProgramData folder in C:\, then check if the folder is hidden. To locate a hidden folder, in the View tab, select show hidden files.

3. To locate and delete the following key, use the following regedit command:

   Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\AmazonSSMAgent

   Note: Use the Microsoft clean-up tool to remove preceding 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.

4. Reboot the server, then manually reinstall SSM Agent.

If the errors persist, then use your SSM Agent logs to troubleshoot your issue.

Related information

Automating updates to SSM Agent

How do I install SSM Agent on an Amazon EC2 Windows instance at launch?

Working with SSM Agent on EC2 instances for Windows Server

Viewing SSM Agent logs