learn

AWS ECS Task Failing — Troubleshooting Guide

Diagnose ECS task failures by separating image, startup, networking, permissions, capacity, and health-check problems.

Troubleshooting

Start with the symptom. End with a verified fix.

What’s wrong?

An ECS task stops shortly after starting or never reaches a healthy running state.

Possible causes

  1. Container image failure
  2. startup command error
  3. missing IAM permission
  4. network or secret access problem
  5. health-check failure
  6. insufficient capacity

Diagnosis

  1. Inspect task and container stop reasons
  2. inspect application logs
  3. verify image and command
  4. validate IAM and networking
  5. inspect health-check behavior

2 · Fix

Correct the confirmed startup or runtime dependency and redeploy.

Verify

Confirm tasks remain healthy through the full deployment and traffic path.

3 · Prevent

Add deployment health checks, structured logs, alarms, and a rollback strategy.

AWS ECS Task Failing

Start with the task stop reason, then follow the container startup path.

Diagnose

  • Inspect ECS task and container stop reasons.
  • Check application logs before changing infrastructure.
  • Verify image, command, environment, secrets, and IAM role.
  • Validate network access to dependencies.
  • Check container health checks and deployment configuration.
  • If capacity is involved, inspect the underlying compute and scheduling signals.

Fix → Verify → Prevent

Make the smallest confirmed correction, redeploy, and observe the service through a complete deployment cycle. Keep stop reasons and rollback steps in the operational runbook.

Engineering companion

Learn → troubleshoot → design → prepare → test

Explore the knowledge graph

Knowledge path

Connected concepts

Explore the knowledge graph