Why can’t I connect to my Amazon EC2 instance using Session Manager?

Last updated: 2021-04-29

I can't access my Amazon Elastic Compute Cloud (Amazon EC2) instance using AWS Systems Manager Session Manager. How can I troubleshoot this issue?

Resolution

Access to an instance using Session Manager can fail due to the following reasons:

  • Incorrect session preferences
  • AWS Identity and Access Management (IAM) permission issues
  • High resource usage on the instance

If you can't connect to Session Manager, then review the following to troubleshoot the issue:

Verify Systems Manager prerequisites

Confirm that the instance appears as a managed instance, and then verify that all Session Manager prerequisites are met. For more information, see Why is my EC2 instance not appearing under Managed Instances in the Systems Manager console?

AWS KMS configuration issues

Review the Session Manager error messages to determine the type of issue. Then, follow the relevant troubleshooting steps to resolve the issue.

Error: "Encountered error while initiating handshake. Handshake timed out. Please ensure that you have the latest version of the session manager plugin"

AWS Key Management Service (AWS KMS) encryption is activated in Session Manager preferences and the instance can't reach the AWS KMS endpoints.

Run the following command to verify connectivity to AWS KMS endpoints. Replace RegionID with your AWS Region.

$ telnet kms.RegionID.amazonaws.com 443

For more information and for instructions to connect to the AWS KMS endpoints, see Connecting to AWS KMS through a VPC endpoint.

Error: "Encountered error while initiating handshake. Fetching data key failed: Unable to retrieve data key, Error when decrypting data key AccessDeniedException"

Confirm that the instance profile or user has the required kms:Decrypt permission for the AWS KMS key that is used to encrypt the session. For more information, see Adding Session Manager permissions to an existing instance profile.

Error: "Invalid Keyname:Your session has been terminated for the following reasons: NotFoundException: Invalid keyId xxxx"

Verify that the AWS KMS key Amazon Resource Name (ARN) that is specified in the Session Manager preferences to encrypt the session is valid. View the available key ARNs, and then confirm that the ARN specified in Session Manager preferences matches one of the available ARNs. For more information, see Finding the key ID and ARN.

RunAs user name is not valid

Error: "Invalid RunAs username"

-or-

Error: "Unable to start shell: failed to start pty since RunAs user xyz does not exist"

Session Manager fails if Enable Run As support for Linux instances is blank or specifies an operating system user name that isn't valid.

To fix this issue, you can provide a valid operating system user name (for example, ubuntu, ec2-user, or centos). Then, verify that the IAM user or role that starts the session is tagged with SSMSessionRunAs = os-user-account-name. The user account must also exist on the operating system. For more information, see Enable run as support for Linux and macOS instances.

Or, you can clear Enable Run As support for Linux instances.

Blank screen displays after starting a session

When you start a session, Session Manager displays a blank screen. For troubleshooting steps, see Blank screen displays after starting a session.

Other troubleshooting

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