Session Manager troubleshooting

Almost every Session Manager failure comes down to one of four things: the agent can't reach the service, the instance profile is missing, the user's IAM policy is missing, or the plugin isn't installed locally. Match your error below.

1. TargetNotConnected

An error occurred (TargetNotConnected) when calling the StartSession operation:
i-0123456789abcdef0 isn't connected.
  • The instance isn't fully set up. Check, in order: SSM Agent running and ≥ 2.3.68.0 (≥ 3.0.222.0 for port forwarding); an instance profile with AmazonSSMManagedInstanceCore (restart the agent after attaching it); outbound 443 to ssm, ssmmessages and ec2messages for the Region, or VPC endpoints for them.
  • Wrong account or Region. AWS lists this explicitly: the error also appears if the instance is in a different account or Region than your CLI profile. Check --region and AWS_PROFILE.

2. "SSM Agent is not online"

The EC2 console's Session Manager tab says the agent "was unable to connect to a Systems Manager endpoint to register itself". This is network: firewall rules, routing, a proxy setting on the agent, or simply no path to the endpoints. Fix the route (NAT, internet gateway or interface endpoints), then restart the agent.

3. "The instance you selected isn't configured to use Session Manager"

The instance is registered with Systems Manager but Session Manager can't use it:

  • The instance profile lacks Session Manager permissions — attach AmazonSSMManagedInstanceCore or the equivalent custom policy.
  • Old SSM Agent — update to 2.3.68.0 or later, manually or with the AWS-UpdateSSMAgent Run Command document.
  • The instance can't reach the endpoints (see above).
  • The instance is out of CPU or memory — AWS notes that a starved instance can be otherwise functional yet unable to establish a session.

4. Instance not in the "Start a session" list

  • Not configured for Systems Manager at all — run Quick Setup → Host Management or attach the profile; AWS notes you "might need to restart the agent" for it to appear.
  • A wrong proxy configuration on the agent can make the node unreachable or report the wrong OS.
  • On the EC2 console, allow a couple of minutes after creating the host management configuration; if two configurations exist, delete the older one.

5. "No permission to start a session" / not authorized

Your IAM policy is missing ssm:StartSession on the instance ARN and on the session document (SSM-SessionManagerRunShell for shells, AWS-StartPortForwardingSession for port forwarding, AWS-StartSSHSession for SSH). Console users also need ssm:DescribeSessions, ssm:GetConnectionStatus, ssm:DescribeInstanceProperties and ec2:DescribeInstances. Sample policies are in Session Manager setup.

AccessDeniedException … ssm:TerminateSession on exit usually means an outdated plugin — update to 1.2.764.0 or later.

6. "SessionManagerPlugin is not found"

The AWS CLI needs the Session Manager plugin installed locally. On Windows the installer should add C:\Program Files\Amazon\SessionManagerPlugin\bin\ to PATH; if the command still fails, add it manually and reopen the prompt. Check with session-manager-plugin --version.

7. Blank screen after starting a session

  • Root volume full on the instance — the agent stops working; free space or use CloudWatch to see disk metrics.
  • Mismatched console URL — the endpoint Region in the URL differs from the ?region= parameter.
  • Logging destination unreachable — instances on VPC endpoints need an s3 gateway endpoint (com.amazonaws.<region>.s3) or a logs interface endpoint if session preferences send output there; a deleted bucket/log group, or an encryption flag set without an encrypted destination, also causes this.

8. Port forwarding stops or the plugin hangs

Local antivirus can deadlock the plugin during port forwarding. Exclude the plugin's install path from scanning.

9. InvalidDocument … Document type: 'Command' is not supported

The --document-name you passed is a Command document, not a Session document. Use one listed under Systems Manager → Documents → Session documents.

10. Linux: "document worker timed out"

The agent log shows failed to create channel: too many open files — too many session worker processes. Raise fs.inotify.max_user_instances (AWS suggests 8192 via Run Command) or terminate stale sessions with aws ssm terminate-session.

Common questions

The agent is running but the instance still won't connect — what's left?

Endpoint reachability. From the instance, confirm it can open 443 to ssmmessages.<region>.amazonaws.com (or that the ssmmessages interface endpoint exists with private DNS enabled). This is the endpoint Session Manager itself uses.

Why does my session end with an AccessDenied on TerminateSession?

Usually an old Session Manager plugin. Update it; if it persists, confirm your policy allows ssm:TerminateSession on arn:aws:ssm:*:*:session/${aws:userid}-*.

Can I see whether the instance is "managed" without starting a session?

Yes — Systems Manager → Fleet Manager lists managed nodes and their agent version and ping status.

Sources