How do I troubleshoot SSM Agent startup issues on my Amazon EC2 Windows instance?

Short description

SSM Agent doesn't start, register, or function correctly when it can't retrieve Amazon EC2 instance metadata from the Instance Metadata Service (IMDS). Incorrect network configurations, proxy settings, and security software interference prevent SSM Agent from retrieving instance metadata.

Important: SSM Agent requires PowerShell 3.0 or later to run Systems Manager documents.

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.

Verify instance health and network configuration

To confirm that your EC2 instance is correctly configured and passes all system and instance health checks, complete the following steps:

1. Open the Amazon EC2 console.

2. Use Remote Desktop Protocol (RDP) to connect to the Windows Server, and then open PowerShell.

3. Run the following command:

   ipconfig /all

   Note: In the output, note the Default Gateway address of the instance.

4. Run the following command to print your route:

   route print

5. Verify that the 169.254.169.254 IMDS route forwards traffic to the Default Gateway IP address that you noted in Step 3.

6. Run the following command to test the connectivity to the IMDS metadata endpoint:

   Test-NetConnection 169.254.169.254 -port 80

7. If the IMDS route doesn't forward traffic to your Default Gateway, then use the route print command to print your route. In the output, verify that the local route for the 169.254.169.254 exists in the output.

Check your SSM Agent logs and service status

Check your SSM Agent logs for error messages at the following locations:

• %PROGRAMDATA%\Amazon\SSM\Logs\amazon-ssm-agent.log
• %PROGRAMDATA%\Amazon\SSM\Logs\errors.log

To check if SSM Agent service is active, open services.msc. Navigate to Amazon SSM Agent and verify that SSM Agent has a Running status. If the service is stopped, then start it manually. If you see an error message, then troubleshoot that error message. For more information, see Troubleshooting SSM Agent.

Verify your version of SSM Agent

Open PowerShell and run the following command to verify your version of SSM Agent:

& 'C:\Program Files\Amazon\SSM\amazon-ssm-agent.exe' -version

In the output, review your SSM Agent version. If the version is outdated, then install the latest version of SSM Agent.

After the installation finishes, run the following command to restart SSM Agent:

 Restart-Service AmazonSSMAgent

Update EC2Launch

Use RDP to connect the Windows Server, and then run the following PowerShell commands to download and install the latest version of EC2Launch v2:

Invoke-WebRequest https://s3.amazonaws.com/amazon-ec2launch-v2/windows/amd64/latest/AmazonEC2Launch.msi -OutFile
$env:USERPROFILE\Desktop\EC2LaunchV2.msi  
$DownloadFile = "$env:USERPROFILE\Desktop\EC2LaunchV2.msi"  
msiexec /i "$DownloadFile" 

When the installation finishes, open services.msc, and then start the Amazon EC2Launch service.

Check proxy settings

If your environment uses a proxy server, then configure SSM Agent to use a proxy.

Use RDP to connect the Windows Server, and then run the following command block in PowerShell:

$serviceKey = "HKLM:\SYSTEM\CurrentControlSet\Services\AmazonSSMAgent"  
$keyInfo = (Get-Item -Path $serviceKey).GetValue("Environment")  
$proxyVariables = @("http_proxy=hostname:port", "https_proxy=example-hostname:example-port", "no_proxy=169.254.169.254")  
  
 if ($keyInfo -eq $null) {  
    New-ItemProperty -Path $serviceKey -Name Environment -Value $proxyVariables -PropertyType MultiString -Force  
} else {  
    Set-ItemProperty -Path $serviceKey -Name Environment -Value $proxyVariables  
}

Note: Replace example-hostname with your proxy server address. Replace example-port with your port number. You must enter your proxy details as the https_proxy variable, even if you use an HTTP proxy.

Then, run the following command to restart SSM Agent:

Restart-Service AmazonSSMAgent

Check for multiple IAM roles attached to the instance

Complete the following steps:

1. Run the following describe-iam-instance-profile-associations AWS CLI command to describe the AWS Identity and Access Management (IAM) roles attached to your instance:

   aws ec2 describe-iam-instance-profile-associations --filters Name=instance-id,Values=example-instance-id

   Note: Replace example-instance-id with your instance ID.
2. In the output, check if you attached multiple IAM roles to your instance. If you attached multiple roles to your instance, then run the following disassociate-iam-instance-profile AWS CLI command to disassociate unnecessary roles:

   aws ec2 disassociate-iam-instance-profile --association-id example-association-id

   Note: Replace example-association-id with the association ID of your IAM instance profile.
3. Verify that the IAM role that remains has the necessary permissions for SSM.

Check for security software issues

Third-party security software, such as antivirus programs, can interfere with SSM Agent functionality. To resolve security software-related issues, complete the following steps:

1. Use RDP to connect to the Windows Server then temporarily deactivate your third-party security software.
2. Open services.msc then navigate to Amazon SSM Agent and confirm that SSM Agent has a Running status.
3. If SSM Agent's status is Running, then add amazon-ssm-agent.exe and the related C:\Program Files\Amazon\SSM\, C:\ProgramData\Amazon\SSM directory to your security software's exclusion list.

Verify PowerShell modules

Complete the following steps to verify that required PowerShell modules are present and aren't corrupted:

1. Run the following command in PowerShell:

   ls env:  
   $env:path -split ';'  
   $PSVersionTable

2. Check the Modules folder at C:\Windows\System32\WindowsPowerShell\v1.0\Modules, and then check for the required modules.

3. To verify that PowerShell works for non-system users, open PowerShell with a standard user, and then run the Get-Host command. Check that PowerShell successfully launches.

If your modules are corrupted or aren't present, then copy them from a known instance that correctly functions.

Reinstall SSM Agent

If the previous steps don't resolve the issue, then complete the following steps to uninstall and reinstall SSM Agent:

1. Use RDP to connect to the Windows Server, and then choose Open Control Panel.
2. Under Programs, choose Uninstall a program.
3. Open the context menu for Amazon SSM Agent, and then choose Uninstall.
4. Rename or delete the SSM folder from following locations:
   C:\ProgramData\Amazon\SSM
   C:\Program Files\Amazon\SSM
5. Reboot your instance.
6. Install the latest version of SSM Agent.