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

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 displaying as a managed node or showing a "Connection lost" status in Systems Manager?

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 with these errors if Enable Run As support for Linux instances specifies an operating system user name that isn't valid.

To fix this issue, provide a valid operating system user name (for example, ubuntu, ec2-user, or centos). The operating system user can be specified by either configuring the session manager preferences or by tagging the IAM user or role that starts the session with the tag key of SSMSessionRunAs and value of os-user-account-name. For more information, see Turn on run as support for Linux and macOS managed nodes.

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?

Related information

Troubleshooting Session Manager

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

Turn on SSH connections through Session Manager

Logging session activity