How do I troubleshoot the "TargetNotConnected" error in Session Manager?

Short description

If AWS Systems Manager can't establish a connection to your target Amazon Elastic Compute Cloud (Amazon EC2) instance, then you receive the "TargetNotConnected" error message. This issue occurs for the following reasons:

• Your EC2 instance doesn't adhere to the Session Manager prerequisites.
• You didn't register the Amazon EC2 instance as a managed node.
• You misconfigured your proxy.
• Service Control Policies (SCPs) block required API actions.
• There are issues with the AWS Systems Manager Agent (SSM Agent).
• There are issues in your Amazon Elastic Container Service (Amazon ECS) container.
• You use a bastion host, and you misconfigured the database.

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version. For information about port forwarding setup, see How do I use Session Manager port forwarding without a bastion host to connect to my EC2 instance through Remote Desktop Protocol (RDP)?

Prerequisites:

• Make sure that you adhere to the Session Manager prerequisites.

• Make sure that your instance appears as Online in Fleet Manager, a capability of AWS Systems Manager. If your instance isn't Online or doesn't appear in Fleet Manager, then see Why can't I use Session Manager to connect to my Amazon EC2 instance?

• To confirm that you're connecting to the correct AWS Region, run the following get AWS CLI command:

  aws configure get region

• To confirm that you're using the correct AWS account, run the following get-caller-identity command:

  aws sts get-caller-identity

Make sure that your instance appears as a managed node

Network routing, virtual private cloud (VPC) security group configuration, and AWS Identity and Access Management (IAM) issues can cause "TargetNotConnected" errors. To troubleshoot these issues, see Why isn't Systems Manager showing my Amazon EC2 instance as a managed instance?

Check your proxy configuration

If your configuration uses a proxy server, then verify that the proxy allows the ssm.region.amazonaws.com Systems Manager endpoint. If your instance is in a Region that launched before 2024, then also make sure that the proxy allows ec2messages.region.amazonaws.com. For instances in a Region that launched in 2024 or later, make sure that the proxy allows ssmmessages.region.amazonaws.com.

Note: Replace region with your Region.

To bypass the proxy and test connectivity, run the following command:

curl -I https://ssm.region.amazonaws.com --noproxy "*"

Note: Replace region with your Region.

If you can connect with the preceding command, then there are proxy issues. Make sure that the SSM Agent proxy configuration for your Windows or Linux instance is correct and matches your network configuration.

Check your SCPs

SCPs at the AWS Organizations level can block required API actions even if you correctly configured your IAM permissions.

To resolve this issue, complete the following steps:

1. Use the IAM policy simulator to test whether the instance's IAM role can run the actions that are listed in the AmazonSSMManagedInstanceCore policy.
2. Check the SCPs that you attached to your organization unit or account to make sure that they allow the ssm:* actions. For instances in a Region that launched before 2024, make sure that the SCPs also allow the ec2messages:* action. For instances in a Region that launched in 2024 or later, make sure that the SCPs allow the ssmmessages:* action.
3. If you updated an SCP, then run the following command to restart SSM Agent based on your operating system (OS).
   Linux:

   sudo systemctl restart amazon-ssm-agent

   Windows:

   Restart-Service AmazonSSMAgent

   Note: You must run the Windows command as a PowerShell administrator.

Troubleshoot SSM Agent issues

Note: For SSM Agent 3.1.501.0 or later, you can use the ssm-cli to troubleshoot managed node availability issues.

Make sure that the SSM Agent status is running. Then, run the following command based on your OS to check the SSM Agent logs.

Linux:

sudo tail -f /var/log/amazon/ssm/amazon-ssm-agent.log

Windows:

Get-Content "C:\ProgramData\Amazon\SSM\Logs\amazon-ssm-agent.log" -Tail 50

Based on what you find in the logs, troubleshoot issues with SSM Agent.

(Amazon ECS only) Check your container configuration

If you use an Amazon ECS container, then take the following actions to troubleshoot "TargetNotConnected" errors.

Make sure that ECS Exec is activated at the task level

Complete the following steps:

1. Open the Amazon ECS console.
2. In the navigation pane, choose Clusters.
3. Select your cluster, and then select your task.
4. Under Configuration, verify that ECS Exec is set to Turned on.
   If ECS Exec isn't activated, then start a new task with ECS Exec activated.

Check your task network mode

For tasks that run on EC2 instances, the network mode affects ECS Exec functionality. It's a best practice to use the awsvpc network mode.

To update your network mode, update the task definition, and then under Network mode, choose awsvpc. Then, update the service to use the new task definition.

Note: To change from bridge to awsvpc, you must also update the networkConfiguration parameter in your service or task configuration to specify subnets and security groups.

Check the networking configuration

Make sure that the Amazon ECS task security groups allow traffic on port 443 and other ports that your configuration uses. Also, confirm that the Amazon ECS task has an IAM role with the required Session Manager permissions.

(Bastion hosts only) Check your database configuration

If you use a bastion host to connect to your database, then run the following command based on your OS to test database connectivity.

Linux:

nc -zv Database_endpoint Database_port

Windows:

Test-NetConnection -ComputerName Database_endpoint -Port Database_port

Note: Replace Database_endpoint with your database endpoint and Database_port with your database port.

If the connection succeeds, then the output shows that the port is open. If the connection fails, then check the security group rules between the bastion and database. Make sure that your database security group has an inbound rule that allows traffic from the bastion host on the database port. Also, verify that the bastion security group has an outbound rule that allows traffic to the database on the database port.

Troubleshoot further

If you still encounter issues, then check your AWS CloudTrail Event history for the following event sources:

• ssm.amazonaws.com
• (Instances in a Region that launched before 2024 only) ec2messages.amazonaws.com
• (Instances in a Region that launched in 2024 or later only) ssmmessages.amazonaws.com

In the Event history, check the failed API calls for specific error codes. AccessDenied and UnauthorizedOperation mean that there are IAM permissions issues, and InvalidUserID.NotFound means that there are instance profile issues.

If you experience connection issues, then connect with an instance in a different subnet or Availability Zone. Or, launch a new instance with the same configuration, and then use the new instance to connect.

Related information

Troubleshooting Session Manager

Starting a session (port forwarding)