How to Fix MongoDB Out of Memory (OOM) on Debian 11

Troubleshooting Guide: MongoDB Out of Memory (OOM) on Debian 11

As Senior DevOps Engineers, we often face the challenge of optimizing resource utilization for critical services. MongoDB, being a powerful document database, can be particularly memory-hungry. An “Out of Memory” (OOM) error on Debian 11 can bring your services to a grinding halt. This guide will walk you through diagnosing and resolving MongoDB OOM issues on Debian 11.

1. The Root Cause: Why this happens on Debian 11

MongoDB’s memory consumption is a critical factor in its stability. When it runs out of available RAM, the Linux kernel’s OOM killer steps in to terminate processes, often targeting MongoDB itself due to its significant memory footprint. On Debian 11, several factors contribute to this:

  • Insufficient RAM: The most obvious reason. If your server simply doesn’t have enough physical memory for MongoDB’s active dataset, indexes, and cache, OOM is inevitable.
  • Inadequate Swap Space: Modern cloud instances of Debian 11 often come with minimal or no pre-configured swap space. When physical RAM is exhausted, swap provides an essential buffer. Without it, the OOM killer is much more aggressive.
  • Linux Kernel Memory Management (vm.overcommit_memory):
    • Debian’s default vm.overcommit_memory value is 0 (heuristic overcommit). This means the kernel attempts to guess if an allocation will succeed, but it might still refuse allocations or invoke the OOM killer if it perceives a risk of running out of memory.
    • Setting this to 1 (always overcommit) allows processes to allocate more memory than physically available, relying on swap or the OOM killer only when actual memory access fails. For databases, 1 is often recommended as it allows MongoDB to manage its own memory more gracefully, deferring the OOM killer until absolute necessity.
  • WiredTiger Cache Sizing: MongoDB’s default WiredTiger storage engine uses a cache that, by default, takes up 50% of the host’s total RAM, minus 1GB. While efficient, this default can be too aggressive if:
    • The server hosts other memory-intensive applications.
    • The database workload fluctuates significantly, or certain operations (e.g., large aggregations, index builds) temporarily demand more.
  • High Workload / Inefficient Queries: A sudden spike in connections, complex aggregation pipelines, or unoptimized queries can temporarily inflate MongoDB’s memory demands, leading to OOM if resources are tightly constrained.

2. Quick Fix (CLI)

These steps aim to provide immediate relief and establish basic memory management best practices. Always connect via SSH.

2.1. Add or Increase Swap Space

This is often the most critical immediate step.

  1. Check existing swap:

    sudo swapon --show
free -h

    If you see little to no swap, proceed.

  2. Create a swap file (e.g., 4GB): Adjust size as needed, typically 2GB to 4GB, or up to the amount of RAM.

    sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

  3. Verify swap is active:

    sudo swapon --show
free -h

  4. Make swap persistent (edit /etc/fstab): Add the following line to the end of /etc/fstab:

    /swapfile none swap sw 0 0

    Self-correction: While you can edit manually, for persistence, ensure the correct fstab entry is added.

2.2. Configure Kernel Memory Overcommit

Setting vm.overcommit_memory to 1 can make the OOM killer less aggressive with memory-hungry processes like MongoDB.

  1. Check current value:

    sysctl vm.overcommit_memory

  2. Set temporarily (until reboot):

    sudo sysctl -w vm.overcommit_memory=1

  3. Make persistent (edit /etc/sysctl.conf): Add or modify the following line in /etc/sysctl.conf:

    vm.overcommit_memory = 1

    Then apply the changes:

    sudo sysctl -p

2.3. Restart MongoDB Service

After applying kernel-level changes, restart MongoDB to ensure it benefits from the new memory management settings.

sudo systemctl restart mongod

3. Configuration Check

After applying quick fixes, delve into MongoDB’s specific configuration.

3.1. Adjust WiredTiger Cache Size

This is the primary MongoDB-specific lever for memory control.

  1. Locate MongoDB configuration file: On Debian 11, this is typically /etc/mongod.conf.

  2. Edit mongod.conf: Open the file with your preferred editor (e.g., sudo nano /etc/mongod.conf).

  3. Modify wiredTiger.engineConfig.cacheSizeGB: By default, MongoDB calculates this as (Total RAM - 1GB) * 0.5. If you have 8GB RAM, this would be (8-1)*0.5 = 3.5GB. If other services are present, or your MongoDB workload is volatile, reduce this. A common starting point for troubleshooting is to reduce it to 25-30% of total RAM, or even less if RAM is very limited.

    Example (for a 8GB RAM system, reducing cache to 2GB):

    storage:
  dbPath: /var/lib/mongodb
  journal:
    enabled: true
  wiredTiger:
    engineConfig:
      cacheSizeGB: 2
      # Other WiredTiger options...

    Self-correction: Emphasize the calculation and reduction strategy clearly.

    Important Considerations:

    • Too small a cache can lead to increased disk I/O and slower performance. It’s a balance.
    • If cacheSizeGB is not explicitly set, MongoDB uses its default calculation. Setting it explicitly overrides this.

  4. Save changes and restart MongoDB:

    sudo systemctl restart mongod

3.2. Review ulimit Settings

While usually handled by the systemd service unit for MongoDB, insufficient ulimit values (especially for nofile - number of open files) can indirectly contribute to resource exhaustion by preventing efficient resource management.

  1. Check systemd override file (if any):

    sudo systemctl cat mongod

    Look for LimitNOFILE, LimitNPROC, etc. If you need to override, create or edit: /etc/systemd/system/mongod.service.d/override.conf

  2. Example override.conf to increase limits:

    [Service]
LimitNOFILE=64000
LimitNPROC=64000

    Then run:

    sudo systemctl daemon-reload
sudo systemctl restart mongod

4. Verification

After implementing changes, it’s crucial to verify their effectiveness.

4.1. Check System Logs for OOM Killer

Look for messages from the OOM killer, which indicate that the system is still under severe memory pressure.

sudo journalctl -xe | grep -i "oom-killer"
dmesg | grep -i "oom-killer"

Ideally, you should see no new OOM killer events after your changes.

4.2. Monitor Memory and Swap Usage

Observe how your system is utilizing RAM and swap.

free -h
sudo swapon --show
htop # (or top) - observe RAM/Swap usage of mongod process

Ensure swap is being used when RAM gets low, and that MongoDB isn’t immediately consuming all available RAM.

4.3. Review MongoDB Logs

Check MongoDB’s logs for any startup messages related to the WiredTiger cache size, or any warnings/errors regarding memory.

sudo less /var/log/mongodb/mongod.log

Look for lines like wiredtiger_cache_size_bytes during startup to confirm your cacheSizeGB setting is being applied.

4.4. Real-time MongoDB Performance Monitoring

Use MongoDB’s built-in tools to observe memory and other resource utilization under load.

mongostat
mongotop

These tools provide insights into page faults, memory usage, and I/O operations, helping you understand if your cache adjustments are performing as expected.

4.5. Test with Typical Workload

The most accurate verification involves simulating your application’s typical (or peak) workload. Monitor the system and MongoDB during these periods to confirm stability and performance.

By systematically addressing swap space, kernel memory overcommit, and MongoDB’s internal cache sizing, you can significantly mitigate OOM issues on Debian 11, ensuring your database remains stable and performs optimally. Remember to iterate and fine-tune these settings based on your specific workload and server resources.

⚡ Related Troubleshooting Guides