Nov 20, 20266 min read

Fix "Essential container in task exited" on ECS

What the ECS stopped reason "Essential container in task exited" means, how to find the exit code and logs before the task disappears, and what exit codes 1, 137, 139 and 143 usually point to on Fargate.

Illustration for Fix "Essential container in task exited" on ECS

ECS stops a whole task as soon as any container marked essential stops, and the stopped reason then reads Essential container in task exited. That line only tells you the trigger.

The cause sits in the container's exit code and its last log lines, and on a Fargate service in a restart loop both disappear quickly. Get those two first, and the fix usually follows.

Exit codes at a glance

Exit codeSignalUsual cause on ECS
0NoneThe process finished, often a script or a server that did not stay in the foreground
1 or 2NoneThe app crashed at startup: missing config, failed migration, unreachable database
137SIGKILL (128 + 9)Out of memory, or no exit within the stop timeout after SIGTERM
139SIGSEGV (128 + 11)Segfault, often a native dependency built for another platform
143SIGTERM (128 + 15)ECS stopped the container, often after failed health checks or a deploy
None, exec format error in logsNoneImage built for arm64 running on X86_64, or the reverse

How do you get the exit code?

The task ARN is in the service's events tab, and describe-tasks returns the stopped reason plus each container's exit code and reason:

~
$ aws ecs describe-tasks --cluster prod --tasks 3f1c2a9b4d5e4f60a1b2c3d4e5f60718 \ --query 'tasks[0].{stopped:stoppedReason,containers:containers[].[name,exitCode,reason]}'{ "stopped": "Essential container in task exited", "containers": [ ["api", 137, "OutOfMemoryError: Container killed due to memory usage"] ]}

Stopped tasks only appear in the console for 1 hour, and an API call after that returns nothing useful. For anything you will debug later, send ECS Task State Change events from EventBridge to a CloudWatch log group, filtered on lastStatus STOPPED, so every stopped reason and exit code is kept.

Where are the logs?

With the awslogs driver, the container's output goes to the log group and stream prefix in the task definition's logConfiguration. If the stream is empty, check three things: the app writes to stdout and stderr rather than a file, the awslogs settings point at a log group that exists or set awslogs-create-group, and the task execution role can write to CloudWatch Logs. A container that crashes before printing anything usually means the entrypoint itself failed, so run the image locally with the same command and environment.

Exit code 1: the app crashed at startup

This is the most common case, and the logs nearly always name it: a required environment variable is missing, a secret did not resolve, a migration failed or the database host is unreachable from the task's subnets. Config that differs between the task definition and your laptop is the usual root cause. Fix the config, register a new task definition revision and update the service. A crash at startup that only happens on ECS is also often a security group that blocks the database port from the task.

Exit code 137: memory or stop timeout

When the container reason says OutOfMemoryError, the process exceeded the container's memory hard limit or the task size. Raise the limit, or keep the runtime below it: set --max-old-space-size for Node, a heap size for the JVM, or fewer worker processes for Python servers, leaving headroom for memory outside the heap.

A 137 without that reason usually means the container ignored SIGTERM. ECS sends SIGTERM, waits for the stopTimeout from the task definition (30 seconds by default on Fargate), then sends SIGKILL. A shell-form CMD makes sh PID 1, and sh does not forward the signal to your process, so use the exec form or an init process.

Exit code 143 and health checks

143 means the process exited cleanly on SIGTERM, so look at why ECS stopped it. The task's stopped reason changes in that case to Task failed container health checks or Task failed ELB health checks rather than the essential container message. Common causes are a health check path that requires auth, an app that listens on a different port than the target group, or a startPeriod and grace period shorter than the app's startup time.

How does Encore keep config failures out of running tasks?

Encore

Encore brings infrastructure from code: a Go service declares its secrets and database in code, and Encore provisions them in your AWS account and runs the service on Fargate or EKS. A deploy fails if a declared secret has no value for the environment, so a missing value never reaches a task that would crash on startup.

Application code passes through Encore and infrastructure guardrails to resources provisioned in your own AWS or GCP account.
Encore provisions the infrastructure your application needs in your own AWS or GCP account.
Get started
brew install encoredev/tap/encore &&
encore app create
Copy

Run in your terminal to get started locally.

~
$ encore app create partner-hooks --example=hello-world$ cd partner-hooks && mkdir -p webhooks/migrations$ encore secret set --type prod,dev,local,pr WebhookSigningKey
// webhooks/webhooks.go package webhooks import ( "crypto/hmac" "crypto/sha256" "encoding/hex" "encoding/json" "io" "net/http" "encore.dev/storage/sqldb" ) // A deploy fails if this secret has no value in the target environment, // so a missing value never reaches a running task. var secrets struct { WebhookSigningKey string } var db = sqldb.NewDatabase("webhooks", sqldb.DatabaseConfig{ Migrations: "./migrations", }) //encore:api public raw method=POST path=/webhooks/partner func Receive(w http.ResponseWriter, req *http.Request) { body, err := io.ReadAll(io.LimitReader(req.Body, 1<<20)) if err != nil { http.Error(w, "read error", http.StatusBadRequest) return } mac := hmac.New(sha256.New, []byte(secrets.WebhookSigningKey)) mac.Write(body) if !hmac.Equal([]byte(hex.EncodeToString(mac.Sum(nil))), []byte(req.Header.Get("X-Signature"))) { http.Error(w, "bad signature", http.StatusUnauthorized) return } var evt struct { ID string `json:"id"` } if err := json.Unmarshal(body, &evt); err != nil || evt.ID == "" { http.Error(w, "missing id", http.StatusBadRequest) return } // Partners retry, so the same event id can arrive more than once. _, err = db.Exec(req.Context(), `INSERT INTO events (id, body) VALUES ($1, $2) ON CONFLICT (id) DO NOTHING`, evt.ID, body) if err != nil { http.Error(w, "store error", http.StatusInternalServerError) return } w.WriteHeader(http.StatusNoContent) }

encore run starts a local Postgres, applies the migration and serves the endpoint. On deploy, the database runs on RDS in private subnets, the service runs on Fargate or EKS, and Encore provisions an IAM role for the service. Logs and traces for each request are collected without configuring a log driver, as the observability docs cover.

A coding agent that adds a secret or a database declares it in Go and runs it locally in the same change, and a value it forgot to set fails the deploy with secret key(s) not defined instead of leaving a task in a restart loop.

Best fit: Teams on ECS who spend time chasing startup crashes caused by config drift between environments.

Frequently asked questions

What does Essential container in task exited mean?

A container marked essential in the task definition stopped, and ECS stops the whole task when any essential container stops. The message only says which event ended the task. The container's exit code and logs say why it stopped.

What does exit code 137 mean on ECS?

The process was killed with SIGKILL, 128 plus signal 9. On ECS that usually means the container hit its memory limit, which the container reason shows as OutOfMemoryError, or it did not exit within the stop timeout after SIGTERM.

Why can I not find my stopped ECS task?

Stopped tasks only appear in the ECS console for 1 hour. To keep the stopped reason and exit codes longer, route ECS Task State Change events from EventBridge to a log group or queue.

How does Encore prevent tasks crashing on missing configuration?

Encore apps declare secrets in code, and a deploy fails if a declared secret has no value in the target environment. A missing value stops the deploy instead of producing tasks that exit on startup.

Deploy to your cloud on AWS and Google Cloud
without managing infrastructure

Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.

~/orders — claude
Claude Code
Claude Code v2.1.180Opus 5.5~/orders