EC2 instance not showing in Systems Manager: fixing SSM Agent registration and Session Manager

#Symptoms

• The instance is running but doesn't appear in Fleet Manager or describe-instance-information.
• It used to appear, but now shows Connection lost.
• Session Manager shows "The version of SSM Agent on the instance does not support Session Manager" or "Target is not connected".
• Run Command and Patch Manager skip the instance.

An instance becomes a managed node only when three things are true: SSM Agent is running, it has credentials (instance profile or Default Host Management Configuration), and it can reach the Systems Manager endpoints on HTTPS. Work through them in that order.

#1. What does Systems Manager see?

aws ssm describe-instance-information \
  --filters Key=InstanceIds,Values=i-0abc123 \
  --query "InstanceInformationList[].{ping:PingStatus,last:LastPingDateTime,agent:AgentVersion,os:PlatformName}"

Also confirm you're looking in the right Region and account. A surprising number of "missing" instances are a CLI profile pointing somewhere else.

#2. Is the agent installed and running?

You need a way onto the box: SSH, RDP, EC2 Serial Console or EC2 Instance Connect. If none work, see the status check and SSH posts first.

# Amazon Linux 2/2023, RHEL (rpm install)
sudo systemctl status amazon-ssm-agent

# Ubuntu (snap install)
sudo snap services amazon-ssm-agent
sudo snap list amazon-ssm-agent

# Windows
Get-Service AmazonSSMAgent

If the service is stopped, start it and read the log:

sudo systemctl restart amazon-ssm-agent
sudo tail -n 100 /var/log/amazon/ssm/amazon-ssm-agent.log
sudo tail -n 50  /var/log/amazon/ssm/errors.log

On Windows the logs are in C:\ProgramData\Amazon\SSM\Logs\.

Tip

Custom or hardened AMIs often don't have the agent at all, or it's disabled by a CIS benchmark script. Bake the agent into your golden image and make sure the service is enabled at boot.

#3. Run the built-in diagnostics

SSM Agent 3.1.501.0 and later include ssm-cli, which checks every requirement in one go:

sudo ssm-cli get-diagnostics --output table

cd "C:\Program Files\Amazon\SSM"
.\ssm-cli.exe get-diagnostics --output table

The checks that matter for registration:

Checks for s3, kms, logs and monitoring are only needed for optional features like session logging and KMS-encrypted sessions.

#4. Credentials: instance profile or DHMC

Check what's attached:

aws ec2 describe-instances --instance-ids i-0abc123 \
  --query "Reservations[].Instances[].{profile:IamInstanceProfile.Arn,imds:MetadataOptions}"

Option A – instance profile. Attach a role with the AWS managed policy AmazonSSMManagedInstanceCore:

aws iam attach-role-policy --role-name ec2-app-role \
  --policy-arn arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore

# No profile attached yet
aws ec2 associate-iam-instance-profile --instance-id i-0abc123 \
  --iam-instance-profile Name=ec2-app-profile

Option B – Default Host Management Configuration (DHMC). Systems Manager supplies credentials to every instance in the account and Region, with no instance profile needed. It requires IMDSv2 and SSM Agent 3.2.582.0 or later. Check whether it's on:

aws ssm get-service-setting \
  --setting-id arn:aws:ssm:eu-west-1:111122223333:servicesetting/ssm/managed-instance/default-ec2-instance-management-role

If an instance profile is attached and grants ssm:UpdateInstanceInformation, the agent uses that and ignores DHMC. If it's attached but has no SSM permissions, the instance falls back to DHMC.

Warning

An explicit deny in an SCP or a permissions boundary on ssm:UpdateInstanceInformation, ssmmessages:* or ec2messages:* blocks registration even when the role looks right. Check CloudTrail for AccessDenied on those calls from the instance role.

After you fix credentials, restart the agent. It can take a few minutes to show as Online. DHMC can take up to 30 minutes to pick up an instance.

#5. Network path to the endpoints

The agent makes outbound HTTPS (443) connections only. No inbound rules are needed.

From the instance:

REGION=eu-west-1
for ep in ssm ec2messages ssmmessages; do
  curl -sS -m 5 -o /dev/null -w "$ep %{http_code} %{remote_ip}\n" https://$ep.$REGION.amazonaws.com
done

Any HTTP code (even 404) means the path works. A timeout means it doesn't.

Private subnet without NAT. Create interface VPC endpoints for ssm, ssmmessages and ec2messages with private DNS enabled. Newer agent versions use ssmmessages in place of ec2messages where they can, but older agents still need ec2messages, so create all three.

for svc in ssm ssmmessages ec2messages; do
  aws ec2 create-vpc-endpoint --vpc-id vpc-0abc --vpc-endpoint-type Interface \
    --service-name com.amazonaws.$REGION.$svc \
    --subnet-ids subnet-0a subnet-0b --security-group-ids sg-0endpoints \
    --private-dns-enabled
done

The endpoint security group must allow inbound 443 from the instance subnets. With endpoints in place, nslookup ssm.$REGION.amazonaws.com should return private IPs. If it returns public IPs, private DNS isn't working. Check that enableDnsSupport and enableDnsHostnames are on for the VPC, and if you use a central DNS setup, check the Route 53 Resolver rules.

Proxy. If outbound traffic goes through a proxy, the agent needs to know. On Linux with systemd, add an override:

sudo systemctl edit amazon-ssm-agent
# [Service]
# Environment="https_proxy=http://proxy.corp:3128"
# Environment="no_proxy=169.254.169.254"
sudo systemctl restart amazon-ssm-agent

Always exclude 169.254.169.254 so IMDS calls don't go to the proxy.

IMDS. If IMDS is disabled, or the hop limit is 1 and the agent runs in a container, the agent can't get credentials:

aws ec2 modify-instance-metadata-options --instance-id i-0abc123 \
  --http-endpoint enabled --http-tokens required --http-put-response-hop-limit 2

#6. Online, but Session Manager still fails

aws ssm start-session --target i-0abc123

#Prevent it next time

• Bake SSM Agent into every AMI and turn on agent auto-update in Fleet Manager settings.
• Turn on DHMC in every Region you use, and enforce IMDSv2 so it works.
• Deploy the three SSM interface endpoints in every VPC that has private-only subnets, as part of your VPC template.
• Alert on drift: a scheduled job comparing describe-instances against describe-instance-information catches unmanaged instances before patch night does.