Why Docker Exec Fails with OOM on a Host with 2 GB Free? Diagnose and Fix vm.min_free_kbytes

Background

When the host has about 2 GB of MemFree, executing docker exec -it oat /bin/bash inside the OAT container unexpectedly returns an out of memory error.

Error Operation

Login to the OAT container fails.

docker exec -it oat /bin/bash

Error Message

OCI runtime state failed: runc did not terminate sucessfully: fatal error: runtime: out of memory

Container Status

# docker ps -f name=oat
CONTAINER ID   IMAGE   COMMAND   CREATED   STATUS   NAMES
dcf4cb4a2c359   reg.docker.alibaba-inc.com/oceanbase/oat:4.3.2_bp1_20250711_x86   "/oat/distribution/p…"   7 hours ago   Up 7 hours   oat

The container is running normally, and OAT can be logged into.

Resource Limits

# docker stats oat --no-stream
CONTAINER ID   NAME   CPU %   MEM USAGE / LIMIT   MEM %   NET I/O   BLOCK I/O   PIDS
cf4cb4a2c359   oat   0.21%   483.3MiB / 3.701GiB   12.75%   0B / 0B   784MB / 95.3MB   97

No memory limits are set for the container, and its memory usage is low.

Check OOM Logs

# grep -E -i 'OOM|out of memory' /var/log/messages
Sep 23 01:31:58 localhost dockerd: ... runtime: out of memory ...

The log only contains the error from the docker exec command.

meminfo

# cat /proc/meminfo
MemTotal:       3880632 kB
MemFree:        2978048 kB
MemAvailable:   0 kB
... (other fields omitted)

Although MemFree is over 2 GB, MemAvailable is reported as 0 KB.

Difference Between MemFree and MemAvailable

MemFree indicates the amount of idle pages, which are not necessarily usable directly.

MemAvailable is calculated by the kernel: MemAvailable ≈ MemFree + reclaimable PageCache + reclaimable Slab – low watermark – reserved memory .

Analysis

The large MemFree but zero MemAvailable suggests that the memory low‑watermark is set too high, causing the kernel to consider the system out of memory.

Memory Watermark Explanation

Linux uses three watermarks (min, low, high) to control memory reclamation.

Min watermark : when memory falls below this, direct reclaim blocks allocations.

Low watermark : when memory falls below this, the kswapd daemon is awakened for asynchronous reclamation.

High watermark : when memory rises above this, kswapd stops reclaiming.

Typical relationship: min < low < high .

Check Watermarks

# awk '/min/ {sum += $2} END {print sum * 4 " KB"}' /proc/zoneinfo
2097148 KB
# sysctl vm.min_free_kbytes
vm.min_free_kbytes = 2097152

The vm.min_free_kbytes is set to 2 GB, which is half of the total 4 GB memory, an unreasonable configuration.

Solution

Reduce vm.min_free_kbytes to a more appropriate value, e.g., 256 MB.

# Temporary change
sysctl -w vm.min_free_kbytes=262144
# Permanent change (add to /etc/sysctl.conf)
name_sysctl="vm.min_free_kbytes"
line="vm.min_free_kbytes=262144"
file="/etc/sysctl.conf"
grep -w -i -q ${name_sysctl} ${file} && \
    sed -i "s/${name_sysctl}.*/${line}/" ${file} || \
    echo "${line}" >> ${file}