Sizing MongoDB WiredTiger cacheSizeGB without starving the OS

The practical answer

Set storage.wiredTiger.engineConfig.cacheSizeGB to a value that leaves room for the operating system page cache, connection buffers, and your application, then restart mongod. A common starting point on a dedicated database host is roughly half of the memory available to MongoDB, but the correct number depends on your working set: the data and indexes your queries actually touch. After the restart, confirm the configured maximum with db.serverStatus().wiredTiger.cache and watch eviction under load.

What the WiredTiger cache actually does

WiredTiger is MongoDB’s default storage engine. Its cache holds data and index pages in memory so queries can avoid disk reads. It is separate from the operating system page cache, which caches file system data such as log files and statistics files that WiredTiger does not manage inside its own cache.

The default cache size is the larger of 50 percent of (total RAM minus 1 GB) or 256 MB. MongoDB 5.0 and later are container-aware and respect cgroup memory limits; older versions may report host memory instead, which can lead to out-of-memory kills inside a container.

When the cache fills, WiredTiger evicts clean pages and writes dirty pages—pages modified by writes—to disk. Sustained high eviction means the cache is too small for the working set, or queries are scanning more data than necessary.

Worked configuration example

Suppose a dedicated host has 16 GB of RAM and runs only mongod. You want a 3 GB WiredTiger cache, leaving memory for the OS page cache, the application, and other processes.

Edit the configuration file

Run this on the mongod host with root or sudo privileges. The config path varies by installation; /etc/mongod.conf is a common location.

storage:
  wiredTiger:
    engineConfig:
      cacheSizeGB: 3

The equivalent startup flag is --wiredTigerCacheSizeGB 3. The value takes effect only after a restart.

Restart mongod

sudo systemctl restart mongod

The service name and config path may differ on your system. Restarting causes a brief outage; on a replica set, restart one node at a time and wait for it to rejoin as SECONDARY before moving to the next.

Verify after restart

Run this in mongosh, the MongoDB shell. You need a user with clusterAdmin privileges or equivalent host-level access.

db.serverStatus().wiredTiger.cache

Check these fields:

• maximum bytes configured: should be close to 3 * 1024 * 1024 * 1024 for the example above.
• bytes currently in the cache: should rise under representative workload and stabilize.
• tracked dirty bytes: fluctuates as writes are applied and checkpoints occur.
• pages evicted by eviction server: should remain low during normal operation; a steadily climbing counter signals cache pressure.

Do not treat a single snapshot as proof. Run the check under a realistic workload and compare eviction rates before and after the change.

Limits and common mistakes

• Allocating all system RAM to the cache. This starves the OS page cache, WiredTiger log files, connection buffers, and the application, increasing swap or OOM risk.
• Ignoring container limits. Confirm that your MongoDB version respects cgroup memory limits. In a container, base cacheSizeGB on the container’s memory limit, not the host’s total RAM.
• Expecting cache tuning to fix missing indexes. A larger cache does not help if queries perform collection scans because supporting indexes are absent. Use explain("executionStats") to check query plans first.
• Tuning every replica set node identically. Size each node based on the memory actually available to that node; read-heavy secondaries may experience different cache pressure than the primary.

Rollback

Because this change modifies mongod.conf and requires a restart, rollback means restoring the previous cacheSizeGB value or removing the setting, then restarting mongod again. After rollback, rerun db.serverStatus().wiredTiger.cache and confirm maximum bytes configured matches the restored value.

Practical way to check the result

Before changing anything, record maximum bytes configured and pages evicted by eviction server under normal load. After applying the new cache size and restarting, repeat the measurement under the same load. The configured maximum should match the new value, and eviction should not increase. If eviction rises or the OS begins swapping, reduce cacheSizeGB and restart again.