Diagnose why an ECS Fargate task fails to start or keeps restarting using DescribeTasks stopCode, service events, and documented stopped-task error codes

Documented steps

1. List recently stopped tasks: aws ecs list-tasks --cluster my-cluster --desired-status STOPPED --region us-east-1
2. Describe each stopped task: aws ecs describe-tasks --cluster my-cluster --tasks <task-arn>; inspect top-level stopCode and stoppedReason plus each containers[].reason and containers[].exitCode.
3. Act promptly — in the console stopped tasks are listed only for about 1 hour after stopping, so pull CLI/API data quickly or rely on CloudWatch Logs / EventBridge for older failures.
4. Match stopCode against ECS's documented categories: TaskFailedToStart, ResourceInitializationError, ResourceNotFoundException, SpotInterruptionError, InternalError, OutOfMemoryError, ContainerRuntimeError, ContainerRuntimeTimeoutError, CannotStartContainerError, CannotStopContainerError, CannotInspectContainerError, CannotCreateVolumeError, CannotPullContainer.
5. For CannotPullContainerError check: execution role has ECR pull permissions; the subnet has a route to the internet (public subnet with public IP, or private subnet with NAT gateway) or VPC endpoints for ECR and S3; the image reference/tag is valid; and whether you are hitting Docker Hub rate limits on unauthenticated pulls.
6. For ResourceInitializationError check connectivity from the task to ECR (registry auth), S3 (env files), SSM/Secrets Manager (secrets), and CloudWatch Logs (the awslogs-group must exist or awslogs-create-group=true). Strings like 'dial tcp', 'TLS handshake timeout', or 'context deadline exceeded' indicate connectivity, not permissions.
7. For OutOfMemoryError, the container exceeded its configured memory limit; raise the task/container memory in the task definition or fix application memory usage.
8. For 'Task failed ELB health checks', verify the ALB/target group covers the AZ the task landed in, the health-check port matches the mapped container port, the health-check path returns 2xx, the timeout covers app startup, and the task security group allows inbound from the ALB security group on that port.
9. Check service-level context: aws ecs describe-services --cluster my-cluster --services my-service and read the events array for messages such as 'unable to place a task because no container instance met all of its requirements' or 'deployment failed: tasks failed to start'.
10. Cross-reference EventBridge 'ECS Service Action' events: INFO events like SERVICE_STEADY_STATE / SERVICE_DEPLOYMENT_COMPLETED indicate health; ERROR events like SERVICE_TASK_PLACEMENT_FAILURE (with a reason such as RESOURCE:CPU or RESOURCE:FARGATE) and SERVICE_DEPLOYMENT_FAILED indicate placement failure or a tripped circuit breaker.
11. For EC2/external launch types, also inspect the container runtime and ECS agent logs on the host, and restart the agent (systemctl restart ecs on Amazon Linux 2/2023) if placement failures cite an AGENT error meaning the agent is disconnected.
12. Official docs: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/stopped-task-errors.html | https://docs.aws.amazon.com/AmazonECS/latest/developerguide/stopped-task-error-codes.html | https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_cannot_pull_image.html | https://docs.aws.amazon.com/AmazonECS/latest/developerguide/resource-initialization-error.html