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 issues prevent Session Manage from connecting to your Amazon EC2 instance:

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

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

Check that you meet the Session Manager prerequisites

Make sure that your EC2 instance and configuration meet the Session Manager prerequisites. For more instructions, see Step 1: Complete Session Manager prerequisites.

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 permissions. For more information, see Sample IAM policies for Session Manager.

Troubleshoot issues in the Session Manager Preferences setting

Check your AWS KMS configuration

The following error message appears when you activate AWS Key Management Service (AWS KMS) encryption in Session Manager, and the instance can't reach the AWS KMS endpoints:

"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 one of the following commands based on your operating system (OS):

• For Linux:

  telnet kms.example-region-id.amazonaws.com 443

• For Windows:

  Test-NetConnection kms.example-region-id.amazonaws.com -port 443

Note: In the previous commands, replace example-region-id with your AWS Region.

If the connection succeeds, you see a blank screen or connection message. If it fails, then you see a connection timeout or refused message. 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 Session Manager returns 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 doesn't exist, then Session Manager returns 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 and then Verify that it's correct. For instructions on how to activate KMS encryption, see Turn on KMS key encryption of session data (console).

Check your Amazon S3 configuration

You receive the following error message when you use log encryption in your Amazon Simple Storage Service (Amazon S3) bucket, and the instance profile lacks s3:GetEncryptionConfiguration permission:

"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 permission 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. For more information about S3 logging configuration, see Logging session data using Amazon S3 (console).

Check your OS configuration

If you activate 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 Session Manager returns 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 plugin issues

If SSM Agent can't create the required files to establish a session, then 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"

For instructions on how to resolve this issue, see Why do I receive the "Plugin with name Standard_Stream not found" error when I use Session Manager to connect to my Amazon EC2 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. The following error message shows that you didn't install the plugin:

"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

Your local machine can't connect to your Session Manager endpoint when your cursor blinks with a blank screen, and you can't interact with the instance.

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

• For Linux:

  telnet ssmmessages.example-region-id.amazonaws.com 443

• For Windows:

  Test-NetConnection ssmmessages.example-region-id.amazonaws.com -port 443

Note: In the previous commands, replace example-region-id with your Region. For more information, see Service endpoints for Systems Manager.

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? and Troubleshooting Session Manager.

Related information

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

Step 8: (Optional) Allow and control permissions for SSH connections through Session Manager

Enabling and disabling session logging

Why isn't Systems Manager showing my Amazon EC2 instance as a managed instance?