# OutOfMemoryError: Container killed due to memory usage

AWS error fixes · Updated 16 November 2026

**Short answer:** The container used more memory than its hard limit, so the kernel killed it (exit code 137) and ECS recorded this reason. Find the limit that applied (the container's memory setting, or the task size on Fargate), compare it with real usage in Container Insights, then either raise the limit or reduce what the process holds. For JVM and Node.js apps, make sure the runtime's heap limit is set below the container limit.

## Which limit was hit

```
aws ecs describe-tasks --cluster prod --tasks <task-arn> \
  --query 'tasks[0].{taskMemory: memory, containers: containers[].[name,exitCode,reason,memory]}'
```

Memory limits can sit at two levels:

| Setting | Effect |
|---|---|
| Container `memory` | Hard limit. Exceed it and the container is killed |
| Container `memoryReservation` | Soft limit used for placement. The container can use more if the instance or task has room |
| Task-level `memory` | Required on Fargate. All containers in the task share it; a sidecar can push the task over |

On EC2 with only `memoryReservation` set, a container is limited by the instance's free memory rather than a fixed figure, so kills there can depend on what else runs on the host.

## Look at real usage

The `AWS/ECS` `MemoryUtilization` metric is a service-wide average, which hides one task spiking. With Container Insights enabled, query per-task memory over time:

```
stats max(MemoryUtilized) as maxMiB, max(MemoryReserved) as limitMiB by TaskId
| filter Type = "Task" and ServiceName = "api"
| sort maxMiB desc
| limit 20
```

Run it against the `/aws/ecs/containerinsights/prod/performance` log group. A steady climb from start to kill suggests a leak; a sudden jump suggests one big request, file or query.

## Fix it

1. **Raise the limit** in a new task definition revision, then deploy it. On Fargate, pick a valid CPU and memory combination; memory options depend on the CPU size.

2. **Cap the runtime's heap below the container limit**, leaving room for non-heap memory:

   ```
   JAVA_TOOL_OPTIONS=-XX:MaxRAMPercentage=75.0
   NODE_OPTIONS=--max-old-space-size=1536
   ```

   Without this, older JVMs and some Node.js versions size themselves from the host's memory, not the container's, and get killed instead of throwing a catchable out-of-memory error.

3. **Bound the work**: stream large files, paginate queries, limit concurrency per task (worker threads, request concurrency), and cap in-memory caches.

4. **Account for sidecars** on Fargate. Log routers and agents use memory from the same task allowance.

5. **Scale out instead of up** if memory grows with load per task: more tasks with target tracking keeps each one below the limit.

## Mistakes to avoid

- Doubling memory without looking at the trend. A leak just takes twice as long to kill the task, and you pay for the memory meanwhile.
- Reading the service-average metric only. One task can be killed repeatedly while the average looks fine.
- Setting the heap equal to the container limit. Threads, buffers and native libraries need memory outside the heap.

## Questions

### What does OutOfMemoryError: Container killed due to memory usage mean?

The container exceeded its hard memory limit and the kernel's OOM killer stopped it. ECS reports it with exit code 137.

### What is the difference between memory and memoryReservation in ECS?

memory is a hard limit that kills the container when exceeded. memoryReservation is a soft limit used for placement; the container may use more if memory is available.

### How do I monitor memory per ECS task?

Enable Container Insights and query MemoryUtilized per task in Logs Insights, or use its per-task metrics. The standard MemoryUtilization metric is an average across the service.

## When this happens away from your desk

Memory kills often start under peak load, when tasks are replaced faster than they can serve traffic. CloudConsole, a phone app for AWS, is built to show memory alarms and stopped-task reasons on your phone so you can see the pattern as it starts.

[About the CloudConsole app](https://cloudconsole.dev/aws-console-app) · [Download on the App Store](https://apps.apple.com/app/cloudconsole-for-aws/id6835419710)

## Sources

- [Amazon ECS stopped task error codes](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/stopped-task-error-codes.html)
- [Amazon ECS Container Insights metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Container-Insights-metrics-ECS.html)

## Related

- [ECS task stopped: Essential container exited with exit code 137](https://cloudconsole.dev/errors/ecs-exit-code-137)
- [Essential container in task exited](https://cloudconsole.dev/errors/ecs-essential-container-exited)
- [CloudWatch alarm for ECS ContainerMemoryUtilization (cluster level)](https://cloudconsole.dev/alarms/ecs-insights-containermemoryutilization)
- [aws ecs register-task-definition](https://cloudconsole.dev/cli/ecs-register-task-definition)
- [Runtime exited with error: signal: killed (Lambda out of memory)](https://cloudconsole.dev/errors/lambda-out-of-memory)
- [How to scale an ECS service](https://cloudconsole.dev/how-to/scale-ecs-service)

---

Source: https://cloudconsole.dev/errors/ecs-outofmemoryerror

CloudConsole is an independent iPhone and Android app for Amazon Web Services by Cloudconcur Ltd. It is not affiliated with Amazon Web Services.
