AWS ECS Task Keeps Stopping with Exit Code 1 — Step-by-Step Fix

An ECS task that starts and immediately stops with exit code 1 is one of the most frustrating debugging experiences in AWS. The task is running, then it is not, and the console shows almost no useful information.

Here is a systematic approach to finding and fixing the root cause.

Step 1: Find the Actual Error

The ECS console's "Stopped reason" column often just says "Essential container in task exited." That tells you nothing useful.

Get the real error from CloudWatch Logs:

# Find the log group for your task
aws ecs describe-task-definition \
  --task-definition your-task-def \
  --query "taskDefinition.containerDefinitions[].logConfiguration"
 
# Get recent log events
aws logs get-log-events \
  --log-group-name /ecs/your-service \
  --log-stream-name ecs/your-container/TASK_ID \
  --limit 50 \
  --query "events[].message" \
  --output text

Or using the AWS Console: ECS → Cluster → Service → Tasks → Click stopped task → Logs tab.

If there are no logs at all: The container is not even starting, which means the issue is before your application code runs — likely an image pull error, missing secret, or IAM permission problem.

Step 2: Check the Exit Code

Different exit codes mean different things:

Get the exact exit code:

aws ecs describe-tasks \
  --cluster your-cluster \
  --tasks TASK_ARN \
  --query "tasks[].containers[].{name:name,exitCode:exitCode,reason:reason}"

Step 3: Fix Exit Code 1 — Application Startup Failures

Exit code 1 almost always means your application threw an unhandled error at startup. Common causes:

Missing environment variables:

# Check what env vars your task definition has
aws ecs describe-task-definition \
  --task-definition your-task-def \
  --query "taskDefinition.containerDefinitions[].environment"
 
# Check what secrets it references
aws ecs describe-task-definition \
  --task-definition your-task-def \
  --query "taskDefinition.containerDefinitions[].secrets"

If your app requires DATABASE_URL and it is not set, you will get exit code 1 with an error like KeyError: DATABASE_URL (Python) or Error: Missing required config: DATABASE_URL (Node).

Secrets Manager / Parameter Store access:

If your task references secrets, the ECS task execution role needs permission to read them:

{
  "Effect": "Allow",
  "Action": [
    "secretsmanager:GetSecretValue",
    "ssm:GetParameters",
    "ssm:GetParameter"
  ],
  "Resource": [
    "arn:aws:secretsmanager:us-east-1:123456789:secret:my-app/*",
    "arn:aws:ssm:us-east-1:123456789:parameter/my-app/*"
  ]
}

Add this policy to the task execution role (not the task role — these are different).

Cannot connect to database or external service:

If your app checks database connectivity at startup and the connection fails, it exits with code 1. Debug by:

# Temporarily add a sleep before your app starts
# In your Dockerfile:
CMD ["sh", "-c", "sleep 30 && node server.js"]
 
# Then exec into the running container and test manually
aws ecs execute-command \
  --cluster your-cluster \
  --task TASK_ARN \
  --container your-container \
  --interactive \
  --command "/bin/sh"
 
# Inside the container:
nc -zv your-rds-endpoint.rds.amazonaws.com 5432

If the database connection fails, check:

1. Security group rules — ECS task security group must allow outbound to RDS security group on port 5432
2. VPC — ECS task and RDS must be in the same VPC or connected VPCs
3. Subnet — if running in private subnets, ensure there is a NAT gateway for internet access

Step 4: Fix Exit Code 137 — OOM Kill

Exit code 137 means the container was killed by the OS for exceeding its memory limit.

Increase the memory limit in your task definition:

{
  "containerDefinitions": [
    {
      "name": "your-app",
      "memory": 2048,
      "memoryReservation": 1024
    }
  ]
}

Or if using Fargate, increase the task-level memory:

aws ecs register-task-definition \
  --family your-task-def \
  --requires-compatibilities FARGATE \
  --network-mode awsvpc \
  --cpu 1024 \
  --memory 2048 \
  # ... rest of config

Find how much memory your app actually needs:

If you have a healthy running instance in another environment, check its memory usage:

# ECS exec into a running container
aws ecs execute-command \
  --cluster your-cluster \
  --task RUNNING_TASK_ARN \
  --container your-container \
  --interactive \
  --command "cat /proc/meminfo | grep MemAvailable"

Or check CloudWatch Container Insights metrics for memory utilization before the crash.

Step 5: Fix Image Pull Errors

If there are no logs at all, the task is likely failing before the container even starts. Check for image pull errors:

aws ecs describe-tasks \
  --cluster your-cluster \
  --tasks TASK_ARN \
  --query "tasks[].stoppedReason"

Look for: CannotPullContainerError: Error response from daemon: pull access denied

For ECR images:

# Verify the image exists
aws ecr describe-images \
  --repository-name your-repo \
  --image-ids imageTag=latest
 
# Ensure the execution role has ECR pull permissions
aws iam attach-role-policy \
  --role-name ecsTaskExecutionRole \
  --policy-arn arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly

For wrong architecture:

If you built an ARM image on an M-series Mac and are running on x86 Fargate, you will get exit code 139 (segfault) or an explicit architecture mismatch error.

Build for the correct platform:

docker buildx build \
  --platform linux/amd64 \
  -t your-image:tag \
  --push .

Quick Diagnosis Checklist

When an ECS task exits immediately:

1. Check CloudWatch Logs for the actual error message
2. Get the exact exit code (aws ecs describe-tasks)
3. If exit code 1: check env vars, secrets access, dependency connectivity
4. If exit code 137: increase memory limit
5. If no logs at all: check image pull errors and execution role IAM
6. If exit code 139: check CPU architecture (ARM vs x86)

Most ECS startup failures are one of these five patterns. The logs tell you which one it is — the frustrating part is knowing where to find them.

More AWS troubleshooting? Check our EKS pods stuck Pending fix and AWS ALB 504 gateway timeout fix.