# ECS Exec: TargetNotConnectedException when calling the ExecuteCommand operation

AWS error fixes · Updated 16 November 2026

**Short answer:** ECS accepted your exec request, but the SSM agent inside the task never connected back to Systems Manager, so there is no session to join. The usual causes are a task role (not execution role) without the ssmmessages permissions, a task with no route to the ssmmessages endpoint, or a task that was started before ECS Exec was turned on.

## What the error looks like

```
An error occurred (TargetNotConnectedException) when calling the
ExecuteCommand operation: The execution command failed due to an
internal error. Try again later.
```

Despite the wording, retrying rarely helps. When ECS Exec is enabled on a task, ECS injects a Systems Manager agent alongside your container. That agent has to open an outbound HTTPS connection to the `ssmmessages` endpoint using the **task role**. If it cannot, the task is "not connected" and every `execute-command` call fails the same way.

## Causes, most common first

1. **Permissions on the wrong role.** The task role needs `ssmmessages:CreateControlChannel`, `ssmmessages:CreateDataChannel`, `ssmmessages:OpenControlChannel` and `ssmmessages:OpenDataChannel`. Adding them to the task execution role does nothing for exec.
2. **No network path.** Tasks in private subnets need a NAT gateway or an interface VPC endpoint for `com.amazonaws.<region>.ssmmessages`, with a security group that allows 443 from the task.
3. **Old tasks.** Turning on `enableExecuteCommand` on a service only affects tasks started afterwards. Existing tasks must be replaced.
4. **Agent not running yet, or stopped.** Right after a task starts, the managed agent may still be initialising.
5. **Read-only root filesystem.** The agent needs to write to the container filesystem; `readonlyRootFilesystem: true` is a known blocker.
6. **KMS encryption on the session.** If the cluster's execute command configuration uses a KMS key, the task role also needs `kms:Decrypt` on it.

## Diagnose in three commands

First confirm exec is enabled on the task itself and look at the managed agent's state:

```
aws ecs describe-tasks --cluster my-cluster \
  --tasks 0123456789abcdef0123456789abcdef \
  --query 'tasks[0].{exec:enableExecuteCommand,agents:containers[].managedAgents}'
```

You want `exec` to be `true` and the `ExecuteCommandAgent` to show `lastStatus: RUNNING`. If `exec` is false, the task predates the setting. Next, find the task role from the task definition and check what it allows:

```
aws ecs describe-task-definition --task-definition my-app:42 \
  --query 'taskDefinition.taskRoleArn'

aws iam list-attached-role-policies --role-name my-app-task-role
```

AWS also publishes an open-source script, `amazon-ecs-exec-checker`, that runs these checks (role, endpoints, agent, read-only filesystem) in one pass.

## Fix it

1. Add an inline or managed policy to the **task role**:

   ```
   {
     "Version": "2012-10-17",
     "Statement": [{
       "Effect": "Allow",
       "Action": [
         "ssmmessages:CreateControlChannel",
         "ssmmessages:CreateDataChannel",
         "ssmmessages:OpenControlChannel",
         "ssmmessages:OpenDataChannel"
       ],
       "Resource": "*"
     }]
   }
   ```

2. For private subnets without NAT, create an interface endpoint for `ssmmessages` in the task's VPC with private DNS enabled.

3. Enable exec on the service and replace the running tasks so they pick up the agent and new permissions:

   ```
   aws ecs update-service --cluster my-cluster --service my-service \
     --enable-execute-command --force-new-deployment
   ```

4. Once the new task shows the agent as RUNNING, connect:

   ```
   aws ecs execute-command --cluster my-cluster \
     --task 0123456789abcdef0123456789abcdef \
     --container app --interactive --command "/bin/sh"
   ```

## Mistakes people make next

- Editing the role and retrying against the same task. Replace the task so it starts with the new configuration.
- Forgetting the Session Manager plugin on the laptop. That produces a different, local error about the plugin not being found, not TargetNotConnected.
- Requesting `/bin/bash` in a slim image that only has `sh`. The session opens and then exits immediately.
- Leaving exec enabled everywhere. It is a shell into production; restrict `ecs:ExecuteCommand` by cluster and tag, and log sessions to CloudWatch or S3.

## Questions

### How do I run a command on an EC2 instance from the AWS CLI?

Use Systems Manager rather than ECS: aws ssm start-session for an interactive shell, or aws ssm send-command with the AWS-RunShellScript document for one-off commands. The instance needs the SSM agent and an instance profile with SSM permissions.

### Does ECS Exec work on Fargate and EC2 launch types?

Yes, on both, as long as the task has exec enabled, the task role has the ssmmessages permissions and the task can reach the ssmmessages endpoint.

### Why does execute-command say exec was not enabled?

That is a different error (InvalidParameterException). It means the task was launched without enableExecuteCommand; update the service with --enable-execute-command and force a new deployment.

## When this happens away from your desk

You usually reach for ECS Exec mid-incident, which is exactly when a broken task role is most painful. CloudConsole, a phone app for AWS, is built to show a service's tasks, their status and recent logs from your phone, so you can triage before you get to a terminal.

[About the CloudConsole app](https://cloudconsole.dev/aws-console-app) · [Download on the App Store](https://apps.apple.com/app/cloudconsole-for-aws/id6835419710)

## Sources

- [Monitor Amazon ECS containers with ECS Exec](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-exec.html)
- [Amazon ECS Developer Guide](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/)

## Related

- [How to exec into an ECS container](https://cloudconsole.dev/how-to/ecs-exec-into-container)
- [aws ecs execute-command](https://cloudconsole.dev/cli/ecs-execute-command)
- [SSM Session Manager: TargetNotConnected](https://cloudconsole.dev/errors/ssm-start-session-targetnotconnected)
- [aws ecs update-service](https://cloudconsole.dev/cli/ecs-update-service)
- [aws ecs describe-tasks](https://cloudconsole.dev/cli/ecs-describe-tasks)
- [AWS ECS force new deployment](https://cloudconsole.dev/how-to/force-new-deployment-ecs)

---

Source: https://cloudconsole.dev/errors/ecs-execute-command-targetnotconnected

CloudConsole is an independent iPhone and Android app for Amazon Web Services by Cloudconcur Ltd. It is not affiliated with Amazon Web Services.
