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.

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.
--sysctland Composesysctls:rejectvm.*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 runs | Where the setting goes | Persists across restart |
|---|---|---|
| Linux host package | /etc/sysctl.d/99-elasticsearch.conf | Yes |
| Docker on Linux | Docker host, same file | Yes, if persisted |
| Docker Compose | Not in sysctls:, host only | Yes, if persisted |
| Kubernetes pod | Privileged init container or node tuning | Per pod, unless tuned on the node |
| Docker Desktop (macOS) | Linux VM via docker run --privileged | No, unless baked into a VM change |
| WSL2 | /etc/sysctl.conf inside the distro | Yes, 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.0ERROR: [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.logThe host fix is two commands and one file:
sudo sysctl -w vm.max_map_count=262144
sysctl vm.max_map_count# /etc/sysctl.d/99-elasticsearch.conf
vm.max_map_count = 262144sudo sysctl --systemsysctl -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.
| Method | Command | Scope | Survives reboot |
|---|---|---|---|
| Runtime write | sysctl -w vm.max_map_count=262144 | Current kernel | No |
| Persistent drop-in | /etc/sysctl.d/99-elasticsearch.conf | Current kernel, reloaded at boot | Yes |
| Node image / boot script | cloud-init, AMI, machine image | Every node of that image | Yes |
The startup checks that usually accompany this one, because fixing only the first is a common waste of a deploy:
| Check | Message | Fix |
|---|---|---|
| Virtual memory areas | vm.max_map_count ... is too low | This article |
| File descriptors | max file descriptors [4096] ... too low | LimitNOFILE=65535 or ulimit |
| Threads | max number of threads ... too low | LimitNPROC, vm.max_map_count usually related |
| Swap | memory locking requested ... but not enabled | bootstrap.memory_lock plus memlock limits |
| Disk watermark | disk usage exceeded flood-stage watermark | Free 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.* keysThe host command is the one that works, and it must run on the machine that runs the Docker daemon, not inside the container:
sudo sysctl -w vm.max_map_count=262144
docker compose up -d elasticsearch
docker compose logs --tail=20 elasticsearch | grep -i bootstrapOn 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:
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: trueThe 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=262144That 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.
# WSL2, inside the distro
echo 'vm.max_map_count=262144' | sudo tee -a /etc/sysctl.conf
sudo sysctl -pVerifying 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:
docker exec -it elasticsearch sysctl vm.max_map_count
# vm.max_map_count = 262144If 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:
# systemd override
[Service]
LimitNOFILE=65535
LimitMEMLOCK=infinity# elasticsearch.yml
bootstrap.memory_lock: trueLimitMEMLOCK=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 documentationThe Linux documentation that defines the behaviour this guide explains.
Try matching browser tools
All toolsSmall utilities that fit Linux work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Linux guides
All Linux guidesnginx 502 Bad Gateway: upstream connection refused
The log line names the address and errno, which is the diagnosis. Fix the host, the start-up order, the buffers, or the timeout that actually fired.
/usr/bin/env: bash with a carriage return: no such file or directory
A CRLF shebang names an interpreter that cannot exist. Normalise the file and stop the next one with .gitattributes.
ENOSPC from inotify: the watcher limit, not the disk
Three per-user limits, one misleading error. Find the consumer, set a permanent sysctl drop-in, and know when polling is the honest answer.
apt: Could not get lock /var/lib/dpkg/lock-frontend
The lock names its holder, so read it instead of deleting the file. Wait, time out, or stop unattended-upgrades for the duration.
More in Linux
All Linux guidesThe guides filed next to this one in Linux, in library order.