Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Elasticsearch: max virtual memory areas vm.max_map_count is too low

The bootstrap check reads a kernel setting that is not namespaced. Set it on the host, persist it with sysctl.d, and tune nodes instead of containers.

~6 min readLinux
#Elasticsearch#Linux#Docker#Kubernetes
A memory map layer stack on a linux kernel base with an amber sysctl dial and a cyan raised value plate

Introduction & Quick Summary

max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144] is a bootstrap check failure from Elasticsearch (and OpenSearch). The JVM started, the distribution check ran, and the node refused to continue because the kernel would not let the process create enough memory maps for Lucene's segment files.

The kernel setting is per host, not per container, so the fix has to be applied where the kernel lives:

  • Bare metal or VM: sysctl -w vm.max_map_count=262144, then persist it in /etc/sysctl.d/.
  • Docker: the value must be set on the Docker host. --sysctl and Compose sysctls: reject vm.* because it is not namespaced.
  • Kubernetes: run a privileged init container that writes the value, or tune the node image.
  • Docker Desktop / WSL2: change the value inside the Linux VM, not on Windows or macOS.
  • Verify with sysctl vm.max_map_count; a container restart does not re-read it.
Where ES runsWhere the setting goesPersists across restart
Linux host package/etc/sysctl.d/99-elasticsearch.confYes
Docker on LinuxDocker host, same fileYes, if persisted
Docker ComposeNot in sysctls:, host onlyYes, if persisted
Kubernetes podPrivileged init container or node tuningPer pod, unless tuned on the node
Docker Desktop (macOS)Linux VM via docker run --privilegedNo, unless baked into a VM change
WSL2/etc/sysctl.conf inside the distroYes, if configured

Core Mechanics, Signatures & Reproducible Setup

vm.max_map_count caps how many memory-mapped regions a single process may create. Lucene memory-maps index files, and a shard with many segments can hold hundreds of maps. Elasticsearch 5 and later require at least 262,144 maps per process at startup, so the default of 65,530 on most distributions is below the floor. The check runs before the node joins the cluster, which is why the process exits instead of degrading.

The value is a kernel-wide limit that is not namespaced. Containers share the host kernel's vm settings, so a container cannot have "its own" maximum map count: docker run --sysctl vm.max_map_count=262144 fails with sysctl 'vm.max_map_count' is not whitelisted, and Compose silently ignores a sysctls: entry for it in some versions.

A reproducible failure is Elasticsearch's own image with the default limits:

docker run --rm docker.elastic.co/elasticsearch/elasticsearch:8.15.0
text
ERROR: [1] bootstrap checks failed. You must address the points described in the following [1] lines before starting Elasticsearch. bootstrap check failure [1] of [1]: max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144] ERROR: Elasticsearch did not exit normally - check the logs at /usr/share/elasticsearch/logs/docker-cluster.log

The host fix is two commands and one file:

bash
sudo sysctl -w vm.max_map_count=262144 sysctl vm.max_map_count
ini
# /etc/sysctl.d/99-elasticsearch.conf vm.max_map_count = 262144
bash
sudo sysctl --system

sysctl -w applies immediately and is forgotten at reboot; sysctl --system loads every file under /etc/sysctl.d, which is what makes it survive.

Key Comparison Table

Three ways to set the same kernel value, with different blast radius.

MethodCommandScopeSurvives reboot
Runtime writesysctl -w vm.max_map_count=262144Current kernelNo
Persistent drop-in/etc/sysctl.d/99-elasticsearch.confCurrent kernel, reloaded at bootYes
Node image / boot scriptcloud-init, AMI, machine imageEvery node of that imageYes

The startup checks that usually accompany this one, because fixing only the first is a common waste of a deploy:

CheckMessageFix
Virtual memory areasvm.max_map_count ... is too lowThis article
File descriptorsmax file descriptors [4096] ... too lowLimitNOFILE=65535 or ulimit
Threadsmax number of threads ... too lowLimitNPROC, vm.max_map_count usually related
Swapmemory locking requested ... but not enabledbootstrap.memory_lock plus memlock limits
Disk watermarkdisk usage exceeded flood-stage watermarkFree space or raise watermark

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

Docker on Linux: set it on the host, not in Compose

Compose sysctls: is for namespaced keys such as net.core.somaxconn. For vm.max_map_count, set the host and start the container normally:

services: elasticsearch: image: docker.elastic.co/elasticsearch/elasticsearch:8.15.0 environment: - discovery.type=single-node - ES_JAVA_OPTS=-Xms1g -Xmx1g ports: - "9200:9200" # sysctls: [ "vm.max_map_count=262144" ] <- rejected for vm.* keys

The host command is the one that works, and it must run on the machine that runs the Docker daemon, not inside the container:

bash
sudo sysctl -w vm.max_map_count=262144 docker compose up -d elasticsearch docker compose logs --tail=20 elasticsearch | grep -i bootstrap

On a shared host this raises the limit for every process, not just Elasticsearch; that is usually fine, since the value is a ceiling, not a reservation.

Kubernetes: tune the node or the pod

Managed node images often ship 262,144, so check before adding workarounds:

bash
kubectl run sysctl-check --rm -it --restart=Never --image=busybox \ --overrides='{"spec":{"nodeName":"ip-10-0-1-23"}}' \ -- sh -c 'sysctl vm.max_map_count'

When the node value is too low and creating your own image is not an option, a privileged init container can raise it before Elasticsearch starts:

initContainers: - name: sysctl image: busybox:1.36 command: ["sh", "-c", "sysctl -w vm.max_map_count=262144"] securityContext: privileged: true

The init container has to run on the same node as the Elasticsearch pod, which is guaranteed for pods in the same spec, and the value then applies to the node until it reboots. Treat it as a stopgap: the durable fix is a node pool with the setting baked in, because a node that restarts without the init container running again returns to 65,530.

Docker Desktop and WSL2

On macOS and Windows, Elasticsearch runs inside a Linux VM, so the Windows or macOS host value is irrelevant. On recent Docker Desktop versions the VM is already at 262,144; older ones are not, and the fix has to reach the VM.

docker run --rm --privileged --pid=host justincormack/nsenter1 \ /sbin/sysctl -w vm.max_map_count=262144

That command re-enters the VM's namespaces and writes the value. It does not persist across a Docker Desktop restart, so for a development setup use the supported route: in WSL2, add the line to /etc/sysctl.conf inside the distro, and in Docker Desktop, keep the engine on a version whose VM ships the value.

bash
# WSL2, inside the distro echo 'vm.max_map_count=262144' | sudo tee -a /etc/sysctl.conf sudo sysctl -p

Verifying from inside the container

sysctl vm.max_map_count inside a container reads the host kernel value, which makes verification easy and also explains why a container restart does not help:

bash
docker exec -it elasticsearch sysctl vm.max_map_count # vm.max_map_count = 262144

If the value reads 65,530 inside the container after you changed the host, you are talking to a different daemon: a remote Docker context, a docker-in-docker builder, or a VM. Check docker context ls and docker info | grep -i server.

After the kernel is fixed, the remaining checks

The bootstrap check list does not stop at one line. A node that clears max_map_count then fails on file descriptors or memory locking, and each failure needs its own setting. Solve them together in one deploy:

yaml
# systemd override [Service] LimitNOFILE=65535 LimitMEMLOCK=infinity
yaml
# elasticsearch.yml bootstrap.memory_lock: true

LimitMEMLOCK=infinity with bootstrap.memory_lock is the pair that clears the "memory locking requested but not enabled" check; raising max_map_count alone leaves you restarting a node that still refuses to start.

Common Compilation/Runtime Mistakes & Version Gotchas

Putting the setting in the container spec. --sysctl vm.max_map_count=... and Compose sysctls: do not apply to vm.*. The daemon rejects or ignores them, and the check fails again with the same number, which makes it look as if the value did not take.

Changing it inside the running container. docker exec ... sysctl -w writes the host value only if the container has the privileges to do it, and the write is lost when the container is replaced. Do it on the host or on the node image.

Forgetting the reload. A file in /etc/sysctl.d does nothing until sysctl --system or a reboot. sysctl vm.max_map_count immediately afterwards is the only proof.

Raising it on the wrong machine. A CI runner that talks to a remote Docker host, or a Kubernetes job that schedules onto an untuned node, changes a kernel nobody is using. Confirm with docker info and the node name.

Assuming OpenSearch and Elasticsearch differ here. Both require 262,144 at startup; the message is nearly identical, so the same fix applies to opensearchproject/opensearch.

Treating it as an Elasticsearch bug. The check exists because exceeding the map limit kills the JVM with a native crash that is far harder to diagnose than a startup refusal. Raising the limit is the supported fix, not a workaround for a defect.

Version floor. The 262,144 requirement is present in Elasticsearch 5 and later, including 8.x; --sysctl whitelist behaviour depends on the container runtime version, not on the image.

The value is read once at process start, so restart the node after changing it and check the log for the bootstrap section rather than assuming success. When you write the persistent config, the YAML validator covers the elasticsearch.yml side, and the Docker Compose reference helps spot a sysctls: entry that will never apply.

Official references: Virtual memory in the Elasticsearch reference and sysctl(8).

Official references

primary documentation

The Linux documentation that defines the behaviour this guide explains.

Try matching browser tools

All tools

Small utilities that fit Linux work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Linux guides

More in Linux

All Linux guides

The guides filed next to this one in Linux, in library order.