Elasticsearch bootstrap.memory_lock Setting

bootstrap.memory_lock instructs Elasticsearch to call mlockall() (or its platform equivalent) at startup, pinning the JVM heap to physical RAM and preventing the kernel from swapping any of it to disk. Swapping any portion of the heap to disk causes garbage collection pauses to balloon from milliseconds to seconds, and frequently triggers cluster instability. Enabling memory locking is one of the standard production bootstrap checks Elasticsearch enforces.

• Default: false
• Recommendation: true in production
• Scope: Static node setting, configured in elasticsearch.yml
• Side effect: Production-mode bootstrap check fails if mlockall cannot be applied

How Memory Locking Works

mlockall(MCL_CURRENT | MCL_FUTURE) is a Linux system call that locks all current and future virtual memory of the calling process into physical RAM. The kernel will not swap locked pages out, even under memory pressure. On Windows, Elasticsearch uses VirtualLock. On macOS, locking is best-effort and rarely used in production.

For the call to succeed, the user running Elasticsearch needs the RLIMIT_MEMLOCK resource limit raised - usually to unlimited. Without that limit, the kernel rejects the lock and Elasticsearch fails its bootstrap check.

Configuring bootstrap.memory_lock

Set it in elasticsearch.yml:

bootstrap.memory_lock: true

You also need to grant the process permission to lock memory. The configuration depends on installation method.

systemd

Edit the unit override (sudo systemctl edit elasticsearch):

[Service]
LimitMEMLOCK=infinity

Then systemctl daemon-reload and restart Elasticsearch.

sysv init / tar.gz installs

In /etc/security/limits.conf:

elasticsearch  soft  memlock  unlimited
elasticsearch  hard  memlock  unlimited

Docker

services:
  elasticsearch:
    ulimits:
      memlock:
        soft: -1
        hard: -1

Kubernetes (ECK)

memlock is unlimited by default for the elasticsearch container in ECK-managed pods. Verify with securityContext and capabilities if running custom manifests.

Verifying Memory Lock Is Active

After startup, check:

GET /_nodes?filter_path=**.mlockall

Each node should report "mlockall": true. If any node shows false while bootstrap.memory_lock: true is set, the bootstrap check should have prevented startup - inspect logs for the actual error.

Common Pitfalls

1. Setting bootstrap.memory_lock: true without raising LimitMEMLOCK or the equivalent ulimit. Elasticsearch refuses to start.
2. Setting -Xmx higher than physical RAM minus OS overhead. With locking enabled, Elasticsearch reserves heap up front and competes with the OS for RAM.
3. Leaving swap enabled on the host. Locking the heap blocks heap swapping, but other Elasticsearch off-heap memory (Lucene caches, network buffers) can still be impacted by swap. Disable swap or set vm.swappiness=1 for best results.
4. Running multiple Elasticsearch processes on one host without per-process locked-memory accounting. The total locked memory must fit in physical RAM.

Monitoring and Operational Notes

A node where memory locking quietly fails after a config change is a recurring production issue, especially after OS upgrades or systemd unit edits.

Prevent Silent mlockall Failures with Pulse

Pulse is an AI DBA for Elasticsearch and OpenSearch that tracks bootstrap.memory_lock and the actual mlockall status on every node, flagging:

• Drift between intended and actual values (a node restarted into a fresh systemd unit that lost LimitMEMLOCK=infinity, or a Docker container that lost ulimits.memlock: -1)
• Settings that are unsafe for your workload (e.g. bootstrap.memory_lock: true requested but the bootstrap check disabled, or heap larger than the locked-memory limit allows)
• The downstream operational impact: swap activity that correlates with multi-second GC pauses, and nodes where vm.swappiness was reset by an OS update

When mlockall quietly becomes false on a single node after a config change, Pulse names the misconfiguration before the next GC freeze.

Connect your cluster.

Frequently Asked Questions

Q: What does bootstrap.memory_lock do in Elasticsearch?
A: bootstrap.memory_lock pins the JVM heap into RAM at process start via mlockall(), preventing the kernel from swapping any heap pages to disk. This avoids multi-second GC pauses caused by paged-out heap.

Q: Why does Elasticsearch fail to start with bootstrap.memory_lock enabled?
A: The process lacks permission to lock memory. Raise LimitMEMLOCK=infinity in the systemd unit, memlock unlimited in /etc/security/limits.conf, or set Docker ulimits.memlock: -1. Check startup logs for the exact error.

Q: How do I verify memory locking is working?
A: Query GET /_nodes?filter_path=**.mlockall. Every node should return "mlockall": true. If false, locking failed silently or bootstrap.memory_lock is not set.

Q: Do I need to disable swap if bootstrap.memory_lock is true?
A: Recommended yes. Memory locking protects the heap but not Lucene memory-mapped files or kernel-level page cache. Setting vm.swappiness=1 or disabling swap entirely is standard production hygiene.

Q: Is bootstrap.memory_lock required in Elasticsearch?
A: It is required in production mode. Elasticsearch runs in production mode when bound to a non-loopback address; the bootstrap check will refuse to start the node if memory locking is requested but fails.

Q: Can I enable bootstrap.memory_lock in Docker or Kubernetes?
A: Yes. In Docker, set ulimits.memlock to -1. In Kubernetes via ECK, locking is enabled by default. In custom manifests, set securityContext capabilities or pod-level securityContext: { fsGroup: ..., runAsUser: ... } with appropriate cluster permissions.

Q: What's the best tool to detect when bootstrap.memory_lock silently fails?
A: Pulse is built for this. It is an AI DBA for Elasticsearch and OpenSearch that continuously checks mlockall status on every node, alerts when locking disappears after a restart or OS update, and correlates swap activity with GC pause spikes - catching the misconfiguration before it causes a multi-second freeze.

Related Reading

• Elasticsearch Heap Size Setting: Sizing the JVM heap
• Elasticsearch JVM Heap Pressure High: Heap-pressure troubleshooting
• Elasticsearch GC Overhead Errors: GC-related instability
• Elasticsearch JVM GC Freeze Analysis: Long GC pauses
• Elasticsearch Settings: Full settings reference