AWS ECS 502 Bad Gateway: Complete Troubleshooting Guide

Understanding AWS ECS 502 Bad Gateway

A 502 Bad Gateway response is generated by your Application Load Balancer (ALB) — not by your container. It means the ALB successfully received the client request, selected a registered target (your ECS task), forwarded the request, but got back an invalid or empty response. The ALB is the gateway; your ECS task is the bad backend.

This is distinct from:

• 504 Gateway Timeout: ALB forwarded the request but the backend took too long to respond.
• 503 Service Unavailable: No healthy targets exist in the target group at all.
• 500 Internal Server Error: Your application returned a valid HTTP response with status 500.

In AWS ECS specifically, 502s almost always originate from one of five layers: health check configuration, network/security group rules, port mapping configuration, application behavior, or timeout mismatches.

Step 1: Establish Scope and Frequency

Before diving into fixes, determine whether the 502 is constant, intermittent, or deployment-triggered. This alone eliminates half the candidate causes.

# Enable ALB access logging first if not already enabled
aws elbv2 modify-load-balancer-attributes \
  --load-balancer-arn $ALB_ARN \
  --attributes Key=access_logs.s3.enabled,Value=true \
               Key=access_logs.s3.bucket,Value=your-logs-bucket \
               Key=access_logs.s3.prefix,Value=alb

If you already have logs, query for 502 patterns:

# Count 502s by target IP in last hour (using CloudWatch Log Insights)
aws logs start-query \
  --log-group-name /aws/applicationloadbalancer/your-alb \
  --start-time $(date -d '1 hour ago' +%s) \
  --end-time $(date +%s) \
  --query-string 'fields @timestamp, target_ip, request_url | filter elb_status_code=502 | stats count() by target_ip | sort count desc'

Also check ECS service events immediately — they often tell the whole story:

aws ecs describe-services \
  --cluster $CLUSTER_NAME \
  --services $SERVICE_NAME \
  --query 'services[0].events[:15]' \
  --output table

Constant 502s → likely health check, security group, or port misconfiguration. Intermittent 502s → likely timeout mismatch, OOM kills, or app-level errors. Deployment-only 502s → draining connections from deregistered tasks.

Step 2: Check Target Group Health

This is the single most productive first check. An unhealthy target group with zero healthy targets will cause 100% of requests to return 502 or 503.

# Get target group ARN for your service
aws elbv2 describe-target-groups \
  --load-balancer-arn $ALB_ARN \
  --query 'TargetGroups[*].{Name:TargetGroupName,ARN:TargetGroupArn,Port:Port,Protocol:Protocol}' \
  --output table

# Check actual health status with reasons
aws elbv2 describe-target-health \
  --target-group-arn $TG_ARN \
  --query 'TargetHealthDescriptions[*].{Target:Target.Id,Port:Target.Port,State:TargetHealth.State,Reason:TargetHealth.Reason,Description:TargetHealth.Description}' \
  --output table

Common TargetHealth.Reason values and what they mean:

Step 3: Verify Port Mapping Configuration

A port mismatch between your application, ECS task definition, and target group is a silent killer — everything looks configured but traffic never reaches the app correctly.

# Check container port mappings in task definition
aws ecs describe-task-definition \
  --task-definition $TASK_DEFINITION_NAME \
  --query 'taskDefinition.containerDefinitions[*].{Name:name,Ports:portMappings}'

# Check what port the target group is sending traffic to
aws elbv2 describe-target-groups \
  --target-group-arns $TG_ARN \
  --query 'TargetGroups[0].{Port:Port,HealthCheckPort:HealthCheckPort,HealthCheckPath:HealthCheckPath}'

For awsvpc network mode (Fargate or ECS with task-level networking), the container port must match the target group port exactly. For bridge mode, the host port in the port mapping must match.

If using dynamic host port mapping (hostPort: 0), the target group must use instance type and ECS registers the ephemeral port automatically.

Step 4: Audit Security Groups

This is the #1 cause of Target.Timeout health check failures. The ECS task's security group must allow inbound TCP traffic from the ALB's security group on the container port.

# Get the ECS service network config
aws ecs describe-services \
  --cluster $CLUSTER_NAME \
  --services $SERVICE_NAME \
  --query 'services[0].networkConfiguration.awsvpcConfiguration'

# Check inbound rules on the ECS task security group
aws ec2 describe-security-groups \
  --group-ids $ECS_TASK_SG_ID \
  --query 'SecurityGroups[0].IpPermissions'

# Get the ALB's security group
aws elbv2 describe-load-balancers \
  --load-balancer-arns $ALB_ARN \
  --query 'LoadBalancers[0].SecurityGroups'

Add the required inbound rule if missing:

aws ec2 authorize-security-group-ingress \
  --group-id $ECS_TASK_SG_ID \
  --protocol tcp \
  --port $CONTAINER_PORT \
  --source-group $ALB_SG_ID

Step 5: Review Application Logs for Errors

If health checks pass but 502s persist, the app is starting and passing health checks but failing on real requests.

# Get the log stream for the running task
TASK_ID=$(aws ecs list-tasks \
  --cluster $CLUSTER_NAME \
  --service-name $SERVICE_NAME \
  --query 'taskArns[0]' \
  --output text | awk -F/ '{print $NF}')

# Tail logs (adjust log group and container name)
aws logs get-log-events \
  --log-group-name /ecs/$SERVICE_NAME \
  --log-stream-name ecs/$CONTAINER_NAME/$TASK_ID \
  --limit 200 \
  --query 'events[*].message' \
  --output text

Look for: unhandled exceptions, segfaults, connection refused errors, or crash loops.

Step 6: Check for OOM Kills and Task Crashes

A container killed by the OOM reaper (exit code 137) or that crashes with exit code 1 while serving a request will cause the ALB to receive a TCP RST — resulting in a 502.

# List recently stopped tasks
aws ecs list-tasks \
  --cluster $CLUSTER_NAME \
  --service-name $SERVICE_NAME \
  --desired-status STOPPED \
  --query 'taskArns[*]' \
  --output text

# Inspect stop reason and exit code
aws ecs describe-tasks \
  --cluster $CLUSTER_NAME \
  --tasks $STOPPED_TASK_ARN \
  --query 'tasks[0].{StoppedReason:stoppedReason,Containers:containers[*].{Name:name,ExitCode:exitCode,Reason:reason}}'

If exitCode is 137, the container was OOM killed. Increase the memory (hard limit) or memoryReservation in your task definition and redeploy.

Step 7: Fix Timeout Mismatches

AWS ECS timeout 502 errors often occur when:

1. ALB idle timeout (default 60 seconds) expires before the backend responds.
2. Your application server closes keepalive connections before ALB does — ALB reuses the connection, gets a RST, and emits 502.

# Increase ALB idle timeout (live change, no redeploy needed)
aws elbv2 modify-load-balancer-attributes \
  --load-balancer-arn $ALB_ARN \
  --attributes Key=idle_timeout.timeout_seconds,Value=120

# Verify current value
aws elbv2 describe-load-balancer-attributes \
  --load-balancer-arn $ALB_ARN \
  --query 'Attributes[?Key==`idle_timeout.timeout_seconds`]'

In your application: set the keepalive timeout to ALB idle timeout + 5 seconds. For nginx: keepalive_timeout 125s;. For Node.js HTTP server: server.keepAliveTimeout = 125000.

Step 8: Fix Health Check Configuration

If your app's health endpoint needs time to warm up, or the path/matcher is wrong:

aws elbv2 modify-target-group \
  --target-group-arn $TG_ARN \
  --health-check-path /health \
  --health-check-interval-seconds 30 \
  --health-check-timeout-seconds 10 \
  --healthy-threshold-count 2 \
  --unhealthy-threshold-count 3 \
  --matcher HttpCode=200-299

# Also increase ECS service health check grace period for slow-starting apps
aws ecs update-service \
  --cluster $CLUSTER_NAME \
  --service $SERVICE_NAME \
  --health-check-grace-period-seconds 60

Step 9: Reduce Deployment-Induced 502s

During rolling updates, ECS deregisters old tasks while registering new ones. Requests to draining tasks return 502. Fix this by:

1. Reducing deregistration delay so old tasks are drained quickly.
2. Ensuring new tasks are healthy before old ones are deregistered.

# Reduce deregistration delay (default 300s is too long)
aws elbv2 modify-target-group-attributes \
  --target-group-arn $TG_ARN \
  --attributes Key=deregistration_delay.timeout_seconds,Value=30

# Ensure rolling update keeps healthy capacity
aws ecs update-service \
  --cluster $CLUSTER_NAME \
  --service $SERVICE_NAME \
  --deployment-configuration minimumHealthyPercent=100,maximumPercent=200

For zero-downtime deployments, migrate to CodeDeploy blue/green which shifts traffic only after new tasks are fully healthy.