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

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:

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

Example of valid configuration:

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

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

# 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.

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

Modern syntax (Compose v3.x with deploy):

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

Legacy syntax (Compose v2.x):

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

Compose v3.9+ shorthand:

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:

docker-compose --compatibility up -d

Check the memory configuration of an existing container:

# 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:

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

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

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

Option 1: Set a very high hard limit

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

Option 2: Omit the hard limit entirely

# 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.