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

Resolution

The following reasons can prevent you from connecting to Session Manager to access an instance:

• 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 follow the troubleshooting steps for your use case.

Check that you meet the Systems Manager prerequisites

Confirm that the instance appears as a managed instance, and then check that you meet all Session Manager prerequisites. For more information, see Why is my EC2 instance not displaying as a managed node or showing a "Connection lost" status in Systems Manager?

Troubleshoot AWS KMS configuration issues

Review the Session Manager error messages to determine the type of issue. Then, follow these 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"

The preceding error means that AWS Key Management System (AWS KMS) encryption is activated in Session Manager preferences, and the instance can't reach the AWS KMS endpoints.

Run the following command to check connectivity to AWS KMS endpoints:

Note: Replace RegionID with your AWS Region.

$ telnet kms.RegionID.amazonaws.com 443

For more information and instructions on connecting 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's used to encrypt the session. For more information, see Adding Session Manager permissions to an existing IAM role.

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

Verify that the AWS KMS encryption key ARN is valid. Check the available key ARNs to confirm that the ARN that's specified in Session Manager preferences matches one of the available ARNs. For more information, see Finding the key ID and key ARN.

Make sure that the RunAs username is valid

Error: "Invalid RunAs username"

-or-

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

If Enable Run As support for Linux instances specifies an operating system (OS) username that isn't valid, then Session Manager fails with these errors.

To resolve this issue, provide a valid OS username (for example, ubuntu, ec2-user, or centos). You can specify the OS in the following ways:

• Configure the Session Manager preferences.
• Tag the IAM user or role that starts the session with the tag key of SSMSessionRunAs and value of os-user-account-name.
• Clear Enable Run As support for Linux instances.

For more information, see Turn on run as support for Linux and macOS managed nodes.

Troubleshoot a blank screen that displays after starting a session

If your screen is blank when you start a Session Manager session, then see Blank screen displays after starting a session.

See other troubleshooting steps

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?

Allow and controlling permissions for SSH connections through Session Manager

Logging session activity