How to Debug AWS Fargate Containers with ECS Exec

You moved to Fargate. No more SSH. No more docker exec. Your container is failing and you can't get inside.

ECS Exec — AWS's answer to docker exec for Fargate — has been around since 2021. It bind-mounts the SSM agent into your running container at runtime. No sidecar. No ports. No keys. Just IAM.

This guide covers setup, the 5 errors that catch everyone, and the production controls you actually need.

Why ECS Exec exists

Fargate has no hosts to SSH into. Before ECS Exec launched in March 2021, debugging a Fargate container meant you couldn't get a shell at all. It was the #1 most requested feature on the AWS Containers Roadmap.

Key fact: ECS Exec is not a sidecar. It bind-mounts the SSM agent binaries into your existing container at runtime. Your task definition doesn't change.

Download the skill file first

Before you hit one of the 5 errors below — there's a skill file on fortem.dev that an AI agent (Claude Code, OpenCode, Codex) can run for you.

It checks:

• Whether --enable-execute-command is set on your service
• Whether the task role has the right SSM permissions
• Whether the Session Manager plugin is installed locally
• Network path to SSM endpoints
• Read-only filesystem settings

Get the ECS Exec Readiness skill file → fortem.dev/blog/ecs-exec-guide

Drop the .md file into your AI agent and it runs the 5-point checklist against your AWS account. Everything runs locally, read-only by default.

The 5 errors that catch everyone

01 — ExecuteCommandAgent not RUNNING

Cause: You forgot --enable-execute-command when creating or updating the service.

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

Verify: aws ecs describe-tasks — check enableExecuteCommand: true and ExecuteCommandAgent status: RUNNING

02 — AccessDeniedException — User is not authorized

Cause: Your task IAM role doesn't have SSM permissions. This is the #1 cause of silent failures.

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

Attach to the task role, not the execution role. The SSM agent runs inside the container — it's the task that needs the permissions.

03 — TargetNotConnected — Session Manager plugin not found

Cause: The SSM Session Manager plugin is not installed on your local machine.

# macOS
curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/mac/sessionmanager-bundle.zip" -o "session.zip"
unzip session.zip
sudo ./sessionmanager-bundle/install -i /usr/local/sessionmanagerplugin -b /usr/local/bin/session-manager-plugin

# Verify
session-manager-plugin --version

04 — Timeout, session never connects

Cause: Your Fargate task can't reach the SSM service endpoint. Either no NAT gateway in the private subnet, or missing VPC endpoints.

# Create VPC endpoint for SSM (recommended for private subnets)
aws ec2 create-vpc-endpoint \
    --vpc-id vpc-xxx \
    --service-name com.amazonaws.region.ssmmessages \
    --subnet-ids subnet-xxx

05 — Session starts but commands fail — cannot create directory

Cause: Your container has readonlyRootFilesystem: true. The SSM agent writes to /var/lib/amazon/ssm/ — it needs a writable filesystem.

"linuxParameters": {
  "initProcessEnabled": true
}

And set readonlyRootFilesystem: false. There's no workaround — the agent needs writable storage.

The happy path — step by step

Step 1 — Install Session Manager plugin (see error 03 above)

Step 2 — Task IAM role policy (see error 02 above — attach ssmmessages:* to task role)

Step 3 — Enable on service:

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

Step 4 — Verify:

aws ecs describe-tasks \
    --cluster my-cluster \
    --tasks $(aws ecs list-tasks --cluster my-cluster --service my-service --query 'taskArns[0]' --output text)
# Look for: "enableExecuteCommand": true, ExecuteCommandAgent "lastStatus": "RUNNING"

Step 5 — Execute:

# Interactive shell
aws ecs execute-command \
    --cluster my-cluster \
    --task YOUR_TASK_ID \
    --container nginx \
    --command "/bin/bash" \
    --interactive

# Single command
aws ecs execute-command \
    --cluster my-cluster \
    --task YOUR_TASK_ID \
    --container nginx \
    --command "env | grep DATABASE" \
    --interactive

Production setup — logging, audit, access control

Three layers for production:

Layer 1 — Log command output

aws ecs update-cluster \
    --cluster my-cluster \
    --configuration executeCommandConfiguration='{
      "logging": "OVERRIDE",
      "logConfiguration": {
        "cloudWatchLogGroupName": "/aws/ecs/my-cluster-exec",
        "s3BucketName": "my-exec-logs",
        "s3KeyPrefix": "exec-output"
      }
    }'

CloudTrail logs who ran ExecuteCommand. S3/CloudWatch logs what they ran.

Layer 2 — Restrict by environment tag

{
  "Effect": "Allow",
  "Action": "ecs:ExecuteCommand",
  "Resource": [
    "arn:aws:ecs:us-east-1:123456789:cluster/my-cluster",
    "arn:aws:ecs:us-east-1:123456789:task/my-cluster/*"
  ],
  "Condition": {
    "StringEquals": {
      "ecs:ResourceTag/environment": "development"
    }
  }
}

Layer 3 — Block production by container name

{
  "Effect": "Deny",
  "Action": "ecs:ExecuteCommand",
  "Resource": "*",
  "Condition": {
    "StringEquals": {
      "ecs:container-name": "production-app"
    }
  }
}

What ECS Exec can't do

"ECS Exec sessions drop after 20 minutes of idle time — this timeout is not configurable. Only one session per container PID namespace is supported, and sessions always run as root regardless of the container USER directive." — AWS ECS Exec documentation, verified June 2026

FAQ

Does ECS Exec work on Fargate Spot?
Yes. The Spot interruption risk means you might lose your exec session mid-debug, but the feature works identically on Spot and On-Demand.

How much does ECS Exec cost?
ECS Exec itself is free. The only potential cost is CloudWatch Logs or S3 storage if you enable session logging. SSM Session Manager is also free. KMS key usage for encryption costs ~$1/month per key.

Can I use ECS Exec to run a one-off command?
Yes: aws ecs execute-command --command 'ls -la' --interactive. For non-interactive use (from CI/CD), omit --interactive.

How do I restrict ECS Exec to specific IAM users?
Use IAM condition keys on ecs:ExecuteCommand. Restrict by cluster name, task tags, container name. Example: allow exec only on tasks tagged environment=development.

What happens to ECS Exec when I update the service?
If you update without --enable-execute-command, new tasks will NOT have ECS Exec. Always include the flag in your update-service calls, or manage it via IaC.

Full article with downloadable skill file: fortem.dev/blog/ecs-exec-guide