CloudConsole

ECS memory vs memoryReservation

Updated 17 November 2026 · How we write and check guides

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.

Timeline: memoryReservation (soft) and memory (hard). Reserved for task placement: soft limit; The container may use: up to…
Where this setting acts, with the default and allowed values from this page.

Side by side

memory (hard limit)memoryReservation (soft limit)
UnitMiBMiB
Effect at runtimeContainer killed if it exceeds itNone directly; under memory pressure Docker tries to push the container back towards it
Used for placement (EC2)Only if no reservation is setYes, subtracted from the instance's available memory
Docker equivalent--memory--memory-reservation
Windows containersSupportedNot supported
RequiredAt 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. The sum of containers' hard limits must fit inside it; it acts as the ceiling for the whole task.

Recommended patterns

SituationContainer memoryReservationContainer memoryTask memory
Fargate, single containerOmitOmit, or a little below task memoryPeak use + 20 to 30%
Fargate, app plus sidecarsSmall values for sidecarsHard limits on sidecars only, so the app can use the restSum of peaks + headroom
EC2, steady workloadTypical usePeak use + headroomOptional
EC2, bursty workload, packing denselyTypical useBurst ceilingOptional
EC2, must never be killed by its own limitTypical useOmit (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

SymptomCause
Stopped reason OutOfMemoryError: Container killed due to memory usage, exit code 137Hard limit too low for real peaks; see OutOfMemoryError
Tasks stuck PENDING with RESOURCE:MEMORY on EC2Reservations (or hard limits) larger than free instance memory
Instances look full in ECS but free shows lots of unused memoryReservations far above real use
Host-level OOM kills of random containersHard 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.

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 app → · Download on the App Store

Sources