Troubleshooting Session Manager - AWS Systems Manager

Troubleshooting Session Manager

Use the following information to help you troubleshoot problems with Session Manager.

No permission to start a session

Problem: You try to start a session, but the system tells you that you do not have the necessary permissions.

No permission to change session preferences

Problem: You try to update global session preferences for your organization, but the system tells you that you do not have the necessary permissions.

Instance not available or not configured for Session Manager

Problem 1: You want to start a session on the Start a session console page, but an instance is not in the list.

  • Solution: The instance you want to connect to might not have been configured to use with the AWS Systems Manager service. To use an instance with Systems Manager, an IAM instance profile that gives Systems Manager permission to perform actions on your instances must be attached to the instance. For information, see Create an IAM instance profile for Systems Manager.

    Note

    If SSM Agent is already running on an instance when you attach the IAM instance profile, you might need to restart the agent before the instance is listed on the Start a session console page.

Problem 2: An instance you want to connect is in the list on the Start a session console page, but the page reports that "The instance you selected is not configured to use Session Manager."

Session Manager Plugin not found

To use the AWS CLI to run session commands, the Session Manager plugin must also be installed on your local machine. For information, see (Optional) Install the Session Manager Plugin for the AWS CLI.

Session Manager Plugin not automatically added to command line path (Windows)

When you install the Session Manager plugin on Windows, the session-manager-plugin executable should be automatically added to your operating system's PATH environment variable. If the command failed after you ran it to check whether the Session Manager plugin installed correctly (aws ssm start-session --target instance-id), you might need to set it manually using the following procedure.

To modify your PATH variable (Windows)

  1. Press the Windows key and enter environment variables.

  2. Choose Edit environment variables for your account.

  3. Choose PATH and then choose Edit.

  4. Add paths to the Variable value field, separated by semicolons, as shown in this example: C:\existing\path;C:\new\path

    C:\existing\path represents the value already in the field. C:\new\path represents the path you want to add, as shown in these examples.

    • 64-bit machines: C:\Program Files\Amazon\SessionManagerPlugin\bin\

    • 32-bit machines: C:\Program Files (x86)\Amazon\SessionManagerPlugin\bin\

  5. Choose OK twice to apply the new settings.

  6. Close any running command prompts and re-open.

TargetNotConnected

Problem: You try to start a session, but the system returns the error message, "An error occurred (TargetNotConnected) when calling the StartSession operation: InstanceID is not connected."

  • Solution: This error is returned when the specified target instance for the session is not fully configured for use with Session Manager. For information, see Getting started with Session Manager.

Blank screen displays after starting a session

Problem: You start a session and Session Manager displays a blank screen.

  • Solution A: This issue can occur when the root volume on the instance is full. Due to lack of disk space, SSM Agent on the instance stops working. To resolve this issue, use Amazon CloudWatch to collect metrics and logs from the operating systems. For information, see Monitoring memory and disk metrics for Amazon EC2 Linux instances or Monitoring memory and disk etrics for Amazon EC2 Windows instances.

  • Solution B: A blank screen might display if you've accessed the console using a link that includes a mismatched endpoint and Region pair. For example, in the following console URL, us-west-2 is the specified endpoint, but us-west-1 is the specified AWS Region:

    https://us-west-2.console.aws.amazon.com/systems-manager/session-manager/sessions?region=us-west-1
  • Solution C: The instance is connecting to Systems Manager using VPC endpoints, and your Session Manager preferences write session output to an Amazon S3 bucket, but an s3 gateway endpoint does not exist in the VPC. An s3 endpoint in the format com.amazonaws.region.s3 is required if your instances are connecting to Systems Manager using VPC endpoints, and your Session Manager preferences write session output to an Amazon S3 bucket. For more information, see Creating VPC endpoints for Systems Manager.