How do I troubleshoot issues with AWS Systems Manager Session Manager?

Last updated: 2021-04-20

The steps to troubleshoot Session Manager issues vary depending on the reason for the session failure.

If a session fails due to any of the following reasons, see Troubleshooting Session Manager for troubleshooting steps:

• No permission to start a session
• No permission to change session preferences
• Instance not available or not configured for Session Manager
• Session Manager plugin not found
• Session Manager plugin not automatically added to command line path (Windows)
• TargetNotConnected
• Blank screen displays after starting a session

Consult the following guidance if a session fails to start and displays one of these error messages:

"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: The ciphertext refers to a AWS KMS key that does not exist, does not exist in this region, or you are not allowed to access. status code: 400, request id: xxxxxxxxxxxx"

The users and instances in your account don’t have the required AWS KMS key (KMS key) permissions. After you enable AWS KMS encryption for your session data, you must grant the required permissions to use the key. You can use Identity and Access Management (IAM) policies to grant permission to use the KMS key with Session Manager.

Important: You must grant KMS key permissions to both the users who start sessions and the instances that the sessions connect to.

• To add KMS key permissions for users in your account, see Quickstart default IAM policies for Session Manager.
• To add KMS key permissions for instances in your account, see Verify or create an IAM instance profile with Session Manager permissions.

For more information about creating and managing AWS KMS keys, see the What is AWS Key Management Service?

"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: Access Denied status code: 403"

You receive this error if you selected Allow only encrypted S3 buckets for S3 Logging in the Session Manager preferences.

To resolve this issue, choose one of the following troubleshooting steps:

• Open the Session Manager preferences. For S3 Logging, clear Allow only encrypted S3 buckets. For more information, see Logging session data using Amazon S3 (console).
• Add a policy to the IAM instance profile that is attached to your instance granting permission to upload encrypted logs to S3. For instructions, see Creating an instance profile with permissions for Session Manager and Amazon S3 and CloudWatch Logs (console).

"Your session has been terminated for the following reasons: We couldn't start the session because encryption is not set up on the selected CloudWatch Logs log group. Either encrypt the log group or choose an option to enable logging without encryption."

You receive this error if you selected Allow only encrypted CloudWatch log groups for CloudWatch Logging in the Session Manager preferences.

To resolve this issue, choose one of the following troubleshooting steps:

• Open the Session Manager preferences. For CloudWatch Logging, clear Allow only encrypted CloudWatch log groups. For more information, see Logging session data using Amazon CloudWatch Logs (console).
• Add a policy to the IAM instance profile that is attached to your instance granting permission to upload encrypted logs to CloudWatch. For instructions, see Creating an instance profile with permissions for Session Manager and Amazon S3 and CloudWatch Logs (console).