How to fix Memory reservation cannot be larger than memory limit in Docker

Q: Is the "Memory reservation cannot be larger than memory limit" error serious?

It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

DockerBEGINNERLOWUpdated Dec 6, 2025· 135 views

This error occurs when you set Docker's --memory-reservation value higher than the --memory (hard limit). Memory reservation is a soft limit that must always be lower than or equal to the hard memory limit.

Quick fix

Fixes Memory reservation cannot be larger than memory limit

# WRONG: reservation (500M) > limit (256M)
docker run --memory=256m --memory-reservation=500m nginx

Understand memory limit vs memory reservation
Fix the memory values in docker run
Fix memory settings in Docker Compose
Verify current container memory settings

docker — error

$# WRONG: reservation (500M) > limit (256M)
docker run --memory=256m --memory-reservation=500m nginx
Memory reservation cannot be larger than memory limit

What this error means

The "Memory reservation cannot be larger than memory limit" error occurs when Docker validates your memory settings and finds that the soft limit (--memory-reservation) exceeds the hard limit (--memory or -m). In Docker's memory model, there are two types of limits: - **Hard limit (--memory)**: The maximum amount of memory a container can use. If the container tries to exceed this, it will be killed (OOM). - **Soft limit (--memory-reservation)**: A target that Docker tries to maintain when memory is contended on the host. The container can use more than this if memory is available, but during memory pressure, Docker will attempt to shrink the container's usage to this reservation. Since the soft limit is meant to be a "floor" that the container can exceed up to the hard limit, it makes no logical sense for the reservation to be higher than the maximum allowed memory. Docker enforces this constraint and refuses to start the container if violated.

Typical symptoms

Container fails to start with 'Memory reservation cannot be larger than memory limit' error
docker run command exits immediately with an error message
Docker Compose fails to bring up services with memory configuration errors
docker-compose up shows validation error for memory settings
Container creation fails in Docker Swarm with resource constraint errors

Common causes

Setting --memory-reservation to a value larger than --memory
Typo or copy-paste error swapping memory and memory-reservation values
Misunderstanding the relationship between soft and hard memory limits
Using mem_reservation larger than mem_limit in Docker Compose
Configuring deploy.resources.reservations.memory higher than deploy.resources.limits.memory
Unit mismatch (e.g., using GB for reservation but MB for limit)

How to fix "Memory reservation cannot be larger than memory limit"

1Understand memory limit vs memory reservation

Before fixing, understand the two settings:

- `--memory` (hard limit): Maximum memory the container can use. Going over this triggers OOM killer.
- `--memory-reservation` (soft limit): Target memory during host memory pressure. Container can exceed this when memory is available.

The rule: reservation must be <= limit

Example of invalid configuration:

bash

# WRONG: reservation (500M) > limit (256M)
docker run --memory=256m --memory-reservation=500m nginx

Example of valid configuration:

bash

# CORRECT: reservation (200M) < limit (500M)
docker run --memory=500m --memory-reservation=200m nginx

2Fix the memory values in docker run

Ensure your --memory-reservation is less than --memory:

bash

# Set a 1GB limit with 512MB reservation
docker run -d \
  --name myapp \
  --memory=1g \
  --memory-reservation=512m \
  myimage:latest

Common memory value formats:
- b - bytes
- k - kilobytes
- m - megabytes
- g - gigabytes

A good rule of thumb: set reservation to 50-75% of the limit. This gives the container headroom to burst while ensuring resources are reclaimed during memory pressure.

3Fix memory settings in Docker Compose

For Docker Compose files, check both the legacy and modern syntax:

Modern syntax (Compose v3.x with deploy):

yaml

services:
  myapp:
    image: myimage:latest
    deploy:
      resources:
        limits:
          memory: 1G
        reservations:
          memory: 512M  # Must be <= limits.memory

Legacy syntax (Compose v2.x):

yaml

services:
  myapp:
    image: myimage:latest
    mem_limit: 1g
    mem_reservation: 512m  # Must be <= mem_limit

Compose v3.9+ shorthand:

yaml

services:
  myapp:
    image: nginx
    mem_limit: 250M
    mem_reservation: 100M  # Must be <= mem_limit

Note: For deploy section to work outside Swarm mode, use the --compatibility flag:

bash

docker-compose --compatibility up -d

4Verify current container memory settings

Check the memory configuration of an existing container:

bash

# View memory limit (returns bytes, 0 = unlimited)
docker inspect --format='{{.HostConfig.Memory}}' <container>

# View memory reservation (returns bytes)
docker inspect --format='{{.HostConfig.MemoryReservation}}' <container>

# View both settings formatted
docker inspect <container> | grep -E "Memory|MemoryReservation"

Example output:

json

"Memory": 536870912,           // 512MB limit
"MemoryReservation": 268435456 // 256MB reservation

To convert bytes to megabytes, divide by 1048576 (1024^2).

5Handle cases where you only want a reservation

If you want a soft limit without a hard cap, you have two options:

Option 1: Set a very high hard limit

bash

docker run -d \
  --memory=8g \
  --memory-reservation=512m \
  myimage:latest

Option 2: Omit the hard limit entirely

bash

# Only sets reservation, no hard limit
docker run -d \
  --memory-reservation=512m \
  myimage:latest

With no --memory flag, the container can use as much memory as available on the host, but Docker will try to reclaim down to the reservation during memory pressure.

Note: Running without a hard limit is risky in production as a memory leak could affect other containers or the host.

Advanced notes

How memory reservation actually works: Memory reservation is enforced through Linux cgroups' soft_limit_in_bytes. When the host experiences memory pressure (low free memory or high page cache demand), the kernel's memory reclaim process will target containers to shrink them toward their reservation value.

Docker Swarm scheduling: In Swarm mode, --reserve-memory affects scheduling decisions. Swarm will only place a task on a node with at least that much memory available. However, it does NOT enforce the reservation at runtime - use --limit-memory for that.

No effect warning: On some systems or Docker Compose versions, memory reservation may be silently ignored. You can verify it was applied:

bash

docker inspect <container> | grep MemoryReservation

If it shows 0, the setting was not applied. This can happen with:
- Docker Compose v3.x without Swarm mode (use --compatibility flag)
- Older Docker versions
- Kernels without cgroup memory controller

Relationship with swap: Memory reservation only applies to RAM, not swap. If you set --memory-swap equal to --memory, swap is disabled and the reservation applies strictly to physical memory usage.

Kubernetes equivalent: In Kubernetes, this concept maps to:

yaml

resources:
  requests:
    memory: "256Mi"   # Similar to --memory-reservation
  limits:
    memory: "512Mi"   # Similar to --memory

Kubernetes also enforces that requests cannot exceed limits.

Frequently asked questions

What does "Memory reservation cannot be larger than memory limit" mean?: The "Memory reservation cannot be larger than memory limit" error occurs when Docker validates your memory settings and finds that the soft limit (--memory-reservation) exceeds the hard limit (--memory or -m). In Docker's memory model, there are two types of limits: - Hard limit (--memory): The maximum amount of memory a container can use. If the container tries to exceed this, it will be killed (OOM).
How do I fix "Memory reservation cannot be larger than memory limit"?: This error occurs when you set Docker's --memory-reservation value higher than the --memory (hard limit). Memory reservation is a soft limit that must always be lower than or equal to the hard memory limit.
What causes "Memory reservation cannot be larger than memory limit"?: Setting --memory-reservation to a value larger than --memory Typo or copy-paste error swapping memory and memory-reservation values Misunderstanding the relationship between soft and hard memory limits
Is the "Memory reservation cannot be larger than memory limit" error serious?: It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading

📚Docker Official Documentation
📖
Docker Docs: Resource constraints(Official Docs)
📖
Docker Docs: Compose Deploy Specification(Official Docs)
💬
Stack Overflow: Memory & CPU limit in Docker Compose v3(Stack Overflow)
🐙
GitHub: Memory reservations have no effect(GitHub)

How to fix Memory reservation cannot be larger than memory limit in Docker

Quick fix

What this error means

Typical symptoms

Common causes

How to fix "Memory reservation cannot be larger than memory limit"

Advanced notes

Frequently asked questions

Related errors

Official resources & further reading