Why can't I use Session Manager to connect to my Amazon EC2 instance?

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.

The following reasons can cause your Session Manager not to connect to your EC2 instance:

• Missing Session Manager prerequisites
• AWS Identity and Access Management (IAM) permission issues
• Incorrect Session Manager Preferences configurations
• Session Manger plug-in issues
• Connectivity issues

To identify the root cause of connection issues and check for error messages, check AWS Systems Manager Agent (SSM Agent) logs.

Check that you meet the Session Manager prerequisites

Make sure that the instance uses managed nodes, and your configuration adheres to the Session Manager prerequisites. For more information, see Why isn't Systems Manager showing my Amazon EC2 instance as a managed instance?

If you run SSM Agent version 3.1.501.0, then you can use the ssm-cli to check whether the instance meets Session Manager prerequisites. The ssm-cli tool determines why Systems Manager doesn't include a running instance in the list of managed instances.

Verify that your IAM user or role has the necessary IAM policies

Confirm that the IAM user or role that you use to connect to the EC2 instance has the necessary IAM policies and permissions for Session Manager.

Troubleshoot issues in the Session Manager Preferences setting

Check your AWS KMS configuration

You can turn on AWS Key Management Service (AWS KMS) encryption in Session Manager. If you turn on AWS KMS and the instance can't reach the AWS KMS endpoints, then you receive the following error message:

"Your session has been terminated for the following reasons: ----------ERROR------- Encountered error while initiating handshake. Handshake timed out. Please ensure that you have the latest version of the session manager plugin."

To check connectivity to your AWS KMS endpoints, run the following command:

telnet kms.RegionID.amazonaws.com 443

Note: Replace RegionID with your AWS Region.

If the output shows that you can't connect to your AWS KMS endpoint, then set up a connection to the AWS KMS virtual private cloud (VPC) endpoint.

If the instance profile or IAM user doesn't have the kms:Decrypt permission on the key, then you receive the following error message:

"Your session has been terminated for the following reasons: ----------ERROR------- Encountered error while initiating handshake. Fetching data key failed: Unable to retrieve data key, Error when decrypting data key AccessDeniedException: User: arn:aws:sts::account id:assumed-role/instance-profile/instance-id is not authorized to perform: kms:Decrypt on resource: arn:aws:kms:region:account id:key/key-id because no identity-based policy allows the kms:Decrypt action status code: 400"

To resolve this issue, add the kms:Decrypt permission for the AWS KMS key that you use to encrypt the session.

If the AWS KMS key Amazon Resource Name (ARN) that you specify in Session Manager isn't correct or no longer exists, then you receive the following error message:

"Your session has been terminated for the following reasons: Error calling KMS GenerateDataKey API: NotFoundException: Key 'arn:aws:kms:region:account:key/abcdxyz' does not exist"

To resolve this issue, check the AWS KMS key ARN to make sure that it's correct.

Check your Amazon S3 configuration

You can store session data in an Amazon Simple Storage Service (Amazon S3) bucket. If you use log encryption and the instance profile doesn't have the s3:GetEncryptionConfiguration permission, then you receive the following error message:

"Your session has been terminated for the following reasons: Couldn't start the session because we are unable to validate encryption on Amazon S3 bucket. Error: AccessDenied: User:abcd is not authorized to perform: s3:GetEncryptionConfiguration on resource"

To resolve this issue, add s3:GetEncryptionConfiguration permissions to the instance profile.

If the S3 bucket that you configured in Session Manager doesn't exist, then you receive the following error message:

"Your session has been terminated for the following reasons: Couldn't start the session because we are unable to validate encryption on Amazon S3 bucket. Error: NoSuchBucket: The specified bucket does not exist status code: 404"

To resolve this issue, verify that the bucket that you specified in Session Manager is correct and available.

Check your OS configuration

If you turn on Run as support on your Linux instances, then you can start sessions with operating system (OS) user credentials. However, if the OS username doesn't exist, then you receive the following error message:

"Your session has been terminated for the following reasons: ----------ERROR------- Unable to start command: failed to start pty since RunAs user username does not exist "

To resolve this issue, make sure that you use the correct default username for your OS, or the custom username is accurate.

Important: You can't use the OS root user account to authenticate connections with Session Manager.

Troubleshoot Session Manager plug-in issues

If the instance's root Amazon Elastic Block Store (Amazon EBS) volume is full, then SSM Agent can't create the required files. You receive the following error message:

"Your session has been terminated for the following reasons: Plugin with name Standard_Stream not found. Step name: Standard_Stream"

To resolve this issue, increase the Amazon EBS volume size, and then extend the file system. Or, delete files that you don't use to free up more disk space on the instance.

If you use the AWS CLI to connect to the instance, then you must install the Session Manager plug-in on your local machine. If you don't install the plug-in, then you receive the following error message:

"SessionManagerPlugin is not found. Please refer to SessionManager Documentation here: http://docs.aws.amazon.com/console/systems-manager/session-manager-plugin-not-found"

Troubleshoot connectivity issues

After you start a Session Manager session, you might see a blank screen with a blinking cursor. If you experience this issue, then your local machine might not be connected to your Session Manager endpoint.

To check connectivity to AWS Session Manager endpoint, run the following command based on your OS.

Linux:

telnet ssmmessages.RegionID.amazonaws.com 443

Note: Replace RegionID with your Region.

Windows:

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

Note: Replace RegionID with your Region.

If your instance is in a private subnet, then see How do I create Amazon Virtual Private Cloud (Amazon VPC) endpoints so that I can use Systems Manager to manage private Amazon EC2 instances without internet access?

For other troubleshooting scenarios, see How do I troubleshoot issues with AWS Systems Manager Session Manager?

Related information

Troubleshooting Session Manager

How can I use an SSH tunnel through Systems Manager to access my private VPC resources?

Allow and control permissions for SSH connections through Session Manager

Turning on and turning off session logging