AWS ECS Task Definition Analyzer

Read a task definition for the reasons a task never starts. Environment variable values are never shown and never leave this page.

Paste below, or drop a file anywhere on this panel

Or drop a file anywhere on this panel. Nothing is uploaded: the analysis runs in this tab.

The answer appears here

Paste on the left and press Analyze. Nothing leaves this tab.

Examples

Real input you can load into the tool above. Each one shows a different thing going wrong, because that is what the tool is for.

An illegal Fargate pairing

Rejected with an error that names the memory, not the pairing

{
  "family": "app",
  "requiresCompatibilities": ["FARGATE"],
  "networkMode": "awsvpc",
  "cpu": "256",
  "memory": "4096",
  "executionRoleArn": "arn:aws:iam::111122223333:role/ecsTaskExecutionRole",
  "taskRoleArn": "arn:aws:iam::111122223333:role/appTaskRole",
  "containerDefinitions": [
    {
      "name": "app",
      "image": "app:1.4.2",
      "essential": true,
      "readonlyRootFilesystem": true,
      "stopTimeout": 60,
      "logConfiguration": { "logDriver": "awslogs", "options": { "mode": "non-blocking" } }
    }
  ]
}

No execution role

CannotPullContainerError, before any of your code runs

{
  "family": "app",
  "requiresCompatibilities": ["FARGATE"],
  "networkMode": "awsvpc",
  "cpu": "512",
  "memory": "1024",
  "taskRoleArn": "arn:aws:iam::111122223333:role/appTaskRole",
  "containerDefinitions": [
    {
      "name": "app",
      "image": "app:1.4.2",
      "essential": true,
      "readonlyRootFilesystem": true,
      "stopTimeout": 60,
      "logConfiguration": { "logDriver": "awslogs", "options": { "mode": "non-blocking" } }
    }
  ]
}

A password in the environment array

In every revision of the definition, readable by every read-only role

{
  "family": "app",
  "requiresCompatibilities": ["FARGATE"],
  "networkMode": "awsvpc",
  "cpu": "512",
  "memory": "1024",
  "executionRoleArn": "arn:aws:iam::111122223333:role/ecsTaskExecutionRole",
  "taskRoleArn": "arn:aws:iam::111122223333:role/appTaskRole",
  "containerDefinitions": [
    {
      "name": "app",
      "image": "app:1.4.2",
      "essential": true,
      "readonlyRootFilesystem": true,
      "stopTimeout": 60,
      "environment": [{ "name": "DB_PASSWORD", "value": "hunter2" }],
      "logConfiguration": { "logDriver": "awslogs", "options": { "mode": "non-blocking" } }
    }
  ]
}

Common mistakes

These are the ones that fail silently. The config is accepted, nothing raises an error, and the consequence arrives later.

  1. Giving the task role permission to read the secrets in the definition

    The ECS agent resolves those secrets before the container starts, using the execution role. The task role is not involved and the task fails to start with a ResourceInitializationError.

    Instead:Put secretsmanager:GetSecretValue and any KMS decrypt permission on the execution role.

  2. Choosing a Fargate memory that is not in the table for that CPU

    Only certain pairings exist. 256 CPU with 4096 MiB is rejected, and the error names the memory rather than the combination.

    Instead:Check the pairing before registering. Raising the CPU is usually cheaper than the outage.

  3. Leaving the awslogs driver in its default blocking mode

    A CloudWatch Logs problem becomes an application outage, because the container blocks on writing to stdout.

    Instead:Set "mode": "non-blocking" and a max-buffer-size in the log options.

The execution role and the task role are different things

The execution role belongs to the ECS agent: pulling the image, writing logs, reading the secrets this definition references. The task role belongs to your application. Getting them confused is the commonest reason a task fails before any code runs.

Because the error blames the wrong thing

A missing execution role produces CannotPullContainerError, which reads like a registry outage or a networking problem, and the task never reaches the point of telling you otherwise. The application's own AWS calls fail differently and later, which is the task role's job.

Fargate accepts only certain CPU and memory pairings

256 CPU units takes 512, 1024 or 2048 MiB and nothing else. 8192 units steps in whole 4 GiB. The API rejects everything outside the table with an error that names the memory value rather than the pairing, so it reads as though the number itself were wrong.

A secret in the environment array is in every revision, forever

ecs:DescribeTaskDefinition returns it in full and every read-only role has that. The secrets array with a valueFrom is the alternative, and the permission to read the referenced secret goes on the EXECUTION role, not the task role, which is the second half of the same confusion.

awslogs blocks the application when CloudWatch is slow

The driver is blocking by default, so a throttle or an outage stops the container writing to stdout, which for most frameworks stops the container. Setting mode to non-blocking with a max-buffer-size drops logs under pressure instead, which is the trade you want.

memory is a hard limit and memoryReservation is a soft one

Crossing memory kills the container immediately, with an OOM that surfaces as an exit code rather than an ECS event. The sum of the container-level limits cannot exceed the task memory, and a registration that breaks that is rejected.

A container gets 30 seconds between SIGTERM and SIGKILL

That is the default stopTimeout, and Fargate caps it at 120. A container that ignores SIGTERM is killed outright, dropping whatever it was serving, and a deployment does that to every task in turn.

More aws tools

AWS IAM Policy Validator & Analyzer Valid JSON? And what does it grant? AWS IAM Policy Evaluator Is this actually allowed? AWS S3 Bucket Policy Analyzer Is this bucket actually public? AWS S3 Bucket Policy Generator Pick a pattern, get a safe policy AWS ARN Decoder Split it up, and check it is right AWS S3 Lifecycle Policy Analyzer Minimum durations you still pay AWS S3 Presigned URL Decoder It dies with the session AWS Lambda Configuration Analyzer Memory is the CPU dial AWS SQS Visibility Timeout Calculator Six times the function timeout AWS EventBridge Pattern Tester Every leaf value is an array AWS DynamoDB Capacity Calculator Every index costs a write AWS Resource Name Validator A dot in a bucket breaks TLS AWS CLI Profile Analyzer The prefix rule is opposite AWS IAM Trust Policy Analyzer Account root means the whole account AWS Access Key ID Identifier AKIA never expires, ASIA does AWS STS Assume Role Command Builder Chaining caps at one hour AWS KMS Key Policy Analyzer The one AWS mistake with no undo AWS Security Group Analyzer They cannot deny anything AWS Network ACL Return Traffic Checker Stateless, so replies need a rule

Elsewhere on the site

Terraform Validator & Formatter Kubernetes YAML Generator Kubernetes YAML Validator Kubernetes Rollout & Probe Timing