# ECS memory vs memoryReservation

AWS configuration · Updated 17 November 2026

**Short answer:** In an ECS container definition, memory is a hard limit in MiB: a container that tries to exceed it is killed (exit code 137, OutOfMemoryError). memoryReservation is a soft limit: ECS subtracts it from the instance's available memory when placing tasks, and the container can use more, up to its hard limit or the memory available on the host. On EC2 a common pattern is memoryReservation at typical use and memory at the most it may ever need; on Fargate the task-level memory size is the real ceiling.

## Side by side

| | `memory` (hard limit) | `memoryReservation` (soft limit) |
|---|---|---|
| Unit | MiB | MiB |
| Effect at runtime | Container killed if it exceeds it | None directly; under memory pressure Docker tries to push the container back towards it |
| Used for placement (EC2) | Only if no reservation is set | Yes, subtracted from the instance's available memory |
| Docker equivalent | `--memory` | `--memory-reservation` |
| Windows containers | Supported | Not supported |
| Required | At least one of the two, when there is no task-level memory | |

If you set both, `memory` must be greater than `memoryReservation`. Docker 20.10 and later need at least 6 MiB per container.

**Task-level memory** (`memory` on the task definition, not the container) is required on Fargate and must be one of the [valid Fargate sizes](https://cloudconsole.dev/limits/fargate-task-size-limits). The sum of containers' hard limits must fit inside it; it acts as the ceiling for the whole task.

## Recommended patterns

| Situation | Container `memoryReservation` | Container `memory` | Task memory |
|---|---|---|---|
| Fargate, single container | Omit | Omit, or a little below task memory | Peak use + 20 to 30% |
| Fargate, app plus sidecars | Small values for sidecars | Hard limits on sidecars only, so the app can use the rest | Sum of peaks + headroom |
| EC2, steady workload | Typical use | Peak use + headroom | Optional |
| EC2, bursty workload, packing densely | Typical use | Burst ceiling | Optional |
| EC2, must never be killed by its own limit | Typical use | Omit (can use all host memory) | Optional |

The last row trades safety for density: without a hard limit, a leak can exhaust the host and the kernel's OOM killer picks a victim, which may be a different container. Use it only with host-level memory alarms.

For JVM, Node.js and Python apps, set the runtime's heap or memory flags relative to the container limit (for example `-XX:MaxRAMPercentage=75`), or the runtime will size itself by what it sees and get killed.

## Example container definition

```
{
  "name": "api",
  "image": "123456789012.dkr.ecr.eu-west-2.amazonaws.com/api:1.42.0",
  "memoryReservation": 512,
  "memory": 1024,
  "essential": true
}
```

On a 4 GiB EC2 instance, ECS will place tasks as if each needs 512 MiB, but any one container is killed if it goes past 1,024 MiB.

**CloudFormation:** `Memory` and `MemoryReservation` on the container definition of `AWS::ECS::TaskDefinition` (and task-level `Memory`). **Terraform:** inside the `container_definitions` JSON of `aws_ecs_task_definition`, using the same camelCase keys; task-level memory is the `memory` argument.

## Symptoms of getting it wrong

| Symptom | Cause |
|---|---|
| Stopped reason `OutOfMemoryError: Container killed due to memory usage`, exit code 137 | Hard limit too low for real peaks; see [OutOfMemoryError](https://cloudconsole.dev/errors/ecs-outofmemoryerror) |
| Tasks stuck PENDING with `RESOURCE:MEMORY` on EC2 | Reservations (or hard limits) larger than free instance memory |
| Instances look full in ECS but `free` shows lots of unused memory | Reservations far above real use |
| Host-level OOM kills of random containers | Hard limits omitted on EC2 with overcommitted reservations |

Check actual usage with Container Insights (`MemoryUtilized` per task and container) before tuning, and alarm on [memory utilisation](https://cloudconsole.dev/alarms/ecs-memoryutilization).

## Questions

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

memory is a hard limit; exceeding it kills the container. memoryReservation is a soft limit used to reserve memory for placement; the container can exceed it up to the hard limit or the host's free memory.

### Do I need memoryReservation on Fargate?

Usually not. On Fargate the task-level memory size is what you pay for and the real ceiling; container limits are mainly useful to cap sidecars.

### What happens if I set only memoryReservation?

On EC2 the container has no hard limit and can use all the memory on the instance. ECS reserves the memoryReservation value for placement.

## When this happens away from your desk

Memory kills tend to cluster at peak traffic, which is rarely when you're at your desk. CloudConsole, a phone app for AWS, is being built to show ECS memory alarms and stopped-task reasons on your phone.

[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 task definition parameters](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html)
- [AWS::ECS::TaskDefinition ContainerDefinition](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-ecs-taskdefinition-containerdefinition.html)

## Related

- [OutOfMemoryError: Container killed due to memory usage](https://cloudconsole.dev/errors/ecs-outofmemoryerror)
- [ECS task stopped: Essential container exited with exit code 137](https://cloudconsole.dev/errors/ecs-exit-code-137)
- [AWS Fargate task size limits](https://cloudconsole.dev/limits/fargate-task-size-limits)
- [service was unable to place a task because no container instance met all of its requirements](https://cloudconsole.dev/errors/ecs-unable-to-place-task)
- [CloudWatch alarm: ECS MemoryUtilization](https://cloudconsole.dev/alarms/ecs-memoryutilization)
- [aws ecs register-task-definition](https://cloudconsole.dev/cli/ecs-register-task-definition)

---

Source: https://cloudconsole.dev/config/ecs-memory-vs-memoryreservation

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