Why can't I start SSM Agent on my Amazon EC2 Windows instance?

Resolution

Note: To determine whether an EC2 instance has the required configuration for a managed node, it's a best practice to use ssm-cli version 3.1.501.0 or later. For more information, see Troubleshooting managed node availability using ssm-cli.

Make sure that the IAM role has the required permissions

The instance's AWS Identity and Access Management (IAM) role must have the required permissions to make API calls to the AWS Systems Manager endpoint. Attach the AmazonSSMManagedInstanceCore policy to the role or make sure that your custom policy includes all the permissions that are listed in AmazonSSMManagedInstanceCore.

Also, make sure that the role's trust policy allows ec2.amazonaws.com to assume the role.

Example trust policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": [
                    "ec2.amazonaws.com",
                    "ssm.amazonaws.com"
                ]
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

Make sure that SSM Agent can access the instance's metadata

SSM Agent must communicate with the instance's metadata service to get the necessary information about the instance. To access your instance's metadata, use the browser within the running instance.

If you use Instance Metadata Service Version 2 (IMDSv2), then run the following command based on your operating system (OS).

Linux:

TOKEN=curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600" \
    && curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/

Windows:

[string]$token = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} -Method PUT -Uri http://169.254.169.254/latest/api/token

Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/latest/meta-data/

Note: For more information, see How Instance Metadata Service version 2 works.

If you can't access the metadata, then run the following command from Windows PowerShell or Command Prompt:

route print 

In the output, confirm that there's a route for 169.254.169.254.

Example output:

Persistent Routes:     
Network Address     Netmask             Gateway Address     Metric  
169.254.169.254     255.255.255.255     172.31.16.1         15  
169.254.169.250     255.255.255.255     172.31.16.1         15  
169.254.169.251     255.255.255.255     172.31.16.1         15  
169.254.169.249     255.255.255.255     172.31.16.1         15  
169.254.169.123     255.255.255.255     172.31.16.1         15  
169.254.169.253     255.255.255.255     172.31.16.1         15

If the route is missing or the gateway address doesn't match the current subnet, then take one of the following actions:

• Run the following command to manually add the route:

  route add -p 169.254.169.254 mask 255.255.255.255 0.0.0.0

  Note: Replace 0.0.0.0 with your instance's gateway address.

• If the instance uses EC2Launch v1, then run the following command from an elevated Windows PowerShell session to add the metadata routes:

  import-Module c:\ProgramData\Amazon\EC2-Windows\Launch\Module\Ec2Launch.psm1 ; Add-Routes

• If the instance uses EC2Launch v2 or EC2Config, then run the following command to restart the services:

  Restart-Service -Name EC2Launch

  Note: The preceding command sets non-persistent static routes to reach the metadata service.

If the route exists but the instance can't retrieve metadata, then verify that your instance's firewall or antivirus configuration doesn't explicitly deny traffic to 169.254.169.254. For more information, see How do I troubleshoot the "Waiting for the metadata service" error on my Amazon EC2 Windows instance?

Make sure that the instance can connect to the required endpoints

To verify that the instance can connect to Systems Manager endpoints on port 443, run the following Windows PowerShell commands:

Test-NetConnection ssm.RegionID.amazonaws.com -port 443

Test-NetConnection ec2messages.RegionID.amazonaws.com -port 443

Test-NetConnection ssmmessages.RegionID.amazonaws.com -port 443

Note: Replace RegionID with the instance's AWS Region.

If the instance can't connect on port 443, then take the following actions based on the type of subnet that the instance is in.

Public subnets

Systems Manager has public endpoints, so your instance must use an internet gateway to reach the internet. Make sure that your instance's route table contains a route to the internet. Also, verify that your Amazon Virtual Private Cloud (Amazon VPC) security groups and network access control lists (network ACLs) allow outbound connections on port 443.

Private subnets

For private subnets, your instance must use a NAT gateway to reach the internet. Or, you must configure the Amazon VPC endpoints to reach Systems Manager endpoints.

For more information about network configuration requirements, see Why isn't Systems Manager showing my Amazon EC2 instance as a managed instance?

Check your proxy settings

If you use proxies, then Systems Manager evaluates and applies the proxy settings to the agent configuration when you start SSM Agent. Make sure that you correctly configured SSM Agent to use a proxy.

Upgrade the SSM Agent

It's a best practice to download and install the latest SSM Agent version. To find the latest SSM Agent versions, see the aws/amazon-ssm-agent Releases on the GitHub website.

Troubleshoot further issues

If the instance still can't start the agent, then view the SSM Agent logs to identify errors that you must troubleshoot.