Andrew Mercer
on this page

MongoDB Troubleshooting

Most of what shows up here is host/OS-level tuning rather than MongoDB configuration — see MongoDB's production notes for the full checklist this page pulls from.

Transparent Huge Pages

A near-universal startup warning on Linux:

** WARNING: /sys/kernel/mm/transparent_hugepage/enabled is 'always'.
**          We suggest setting it to 'never'
** WARNING: /sys/kernel/mm/transparent_hugepage/defrag is 'always'.
**          We suggest setting it to 'never'

Transparent Huge Pages (THP) is a Linux memory-management feature that hurts WiredTiger's (MongoDB's default storage engine) performance under typical workloads — it optimizes for large contiguous allocations, which isn't the access pattern WiredTiger's internal caching does. Disable it, not just silence the warning.

One-Time Fix

echo never | sudo tee /sys/kernel/mm/transparent_hugepage/enabled
echo never | sudo tee /sys/kernel/mm/transparent_hugepage/defrag

This reverts on reboot — fine for a quick test, not for production.

Persistent Fix: systemd Unit

# /etc/systemd/system/mongodb-hugepage-fix.service
[Unit]
Description="Disable Transparent Hugepage before MongoDB boots"
Before=mongodb.service

[Service]
Type=oneshot
ExecStart=/bin/bash -c 'echo never > /sys/kernel/mm/transparent_hugepage/enabled'
ExecStart=/bin/bash -c 'echo never > /sys/kernel/mm/transparent_hugepage/defrag'

[Install]
RequiredBy=mongodb.service

Double-check the Before=/RequiredBy= service name matches whatever your actual MongoDB unit is called (mongodb.service vs. mongod.service differs by distro/package).

sudo systemctl daemon-reload
sudo systemctl enable mongodb-hugepage-fix
sudo systemctl start mongodb-hugepage-fix
sudo systemctl restart mongodb

Persistent Fix: sysfsutils

An alternative for distros without easy systemd unit ordering control:

sudo aptitude install sysfsutils

# /etc/sysfs.conf
kernel/mm/transparent_hugepage/enabled = never
kernel/mm/transparent_hugepage/defrag = never

NUMA

On multi-socket hosts, MongoDB (and databases generally) can suffer from uneven memory access latency if the kernel's NUMA-aware memory reclaim behavior interacts badly with the database's own memory management. Disable zone reclaim:

echo 0 | sudo tee /proc/sys/vm/zone_reclaim_mode
# or, persistently:
sudo sysctl -w vm.zone_reclaim_mode=0

Start mongod with interleaved memory allocation across NUMA nodes rather than pinned to one:

numactl --interleave=all mongod <options>

See MongoDB: Hardware Considerations for the fuller rationale — this matters most on larger multi-socket servers and is largely a non-issue on single-socket hardware.

Flushing the OS Page Cache

Covered in Overview: Flushing OS-Level Caches — a diagnostic tool, not routine maintenance.

  • Overview — install and basic operations
  • Replication — the huge-pages warning is especially common when starting several mongod instances at once for a replica set