How to configure WiredTiger cache in MongoDB.

Complete 2026 Guide — sizing, container adjustments, and monitoring.

The WiredTiger cache is, on its own, the single most impactful parameter for MongoDB's read performance. Misconfigured, it's the most common cause of read latency in production that seems "random" — and while the default configuration is reasonable for most cases, it's frequently wrong for containers, shared servers, and workloads with a predictable access pattern.

What the WiredTiger cache is

Since version 3.2, WiredTiger has been MongoDB's default storage engine. It keeps an in-memory cache of the most frequently accessed data and indexes — the so-called working set. When a query finds the data in cache, the response is essentially instant; when it doesn't, WiredTiger has to fetch from disk, and the latency gap between the two scenarios is typically one to two orders of magnitude.

Sizing this cache correctly is the line between a fast MongoDB and one that "chokes" under load with no obvious explanation on the CPU dashboard.

The default value — and why it doesn't always fit

By default, MongoDB reserves for the WiredTiger cache the larger of 50% of available RAM minus 1 GB, or 256 MB:

wiredTigerCacheSizeGB = max((RAM_GB − 1) × 0.5, 0.25)

On a dedicated server with 32 GB of RAM, that works out to roughly 15.5 GB of cache — a reasonable starting point, since it leaves the rest of memory for the operating system's filesystem cache, which also accelerates reads (MongoDB's compressed data files get cached by the OS independently of the WiredTiger cache).

The problem shows up in three recurring scenarios:

1. Containers and Kubernetes. Older MongoDB versions may fail to correctly detect a container's memory limit (cgroup) and calculate the cache based on the host's total RAM instead of the allocated limit — a recipe for an OOM kill. Recent versions detect cgroups correctly, but setting the value explicitly remains the safer practice.
2. Multiple instances on the same server. If more than one mongod runs on the same machine, the default calculation doesn't account for that — each instance will try to reserve 50% of total RAM, and the sum easily exceeds available physical memory.
3. Workloads with a known working set. If the active dataset is much smaller than available RAM, a larger-than-necessary cache doesn't help — and in specific scenarios can compete for memory with the OS filesystem cache in counterproductive ways.

How to configure it explicitly

The most reliable way to set the cache size is directly in mongod.conf:

storage:
  dbPath: /var/lib/mongodb
  wiredTiger:
    engineConfig:
      cacheSizeGB: 8

In a container with a 4 GB memory limit, for example, an explicit, conservative value (leaving headroom for the mongod process, connections, and OS overhead) is preferable to trusting the automatic calculation:

storage:
  wiredTiger:
    engineConfig:
      cacheSizeGB: 2

Worth repeating: even in environments that detect cgroups correctly, setting the value explicitly removes a variable of uncertainty — particularly relevant in environments with automated deployments and varying instance sizes.

Adjusting it at runtime, without a restart

Since MongoDB 3.2, the cache size can be changed at runtime, with zero downtime:

db.adminCommand({
  setParameter: 1,
  wiredTigerEngineRuntimeConfig: "cache_size=6G"
})

Note: this change is temporary — it holds until the next process restart. To make the change permanent, mongod.conf also needs to be updated with the new value. Forgetting this second step is a common mistake: the team tests the runtime adjustment, validates the performance gain, and weeks later a routine maintenance restart silently reverts it to the old value.

How to monitor actual cache usage

Before making any adjustment, measure first. The command below returns the configured value, in bytes:

db.serverStatus().wiredTiger.cache["maximum bytes configured"]
// result in bytes — divide by 1073741824 to get GB

For a more complete view of cache behavior:

const cache = db.serverStatus().wiredTiger.cache;
print("Configured (GB):", cache["maximum bytes configured"] / 1073741824);
print("Currently in use (GB):", cache["bytes currently in the cache"] / 1073741824);
print("Read into cache (bytes):", cache["bytes read into cache"]);
print("Written from cache (bytes):", cache["bytes written from cache"]);

Signs the cache is undersized

• Utilization consistently above 90% combined with a high eviction rate — WiredTiger is being forced to free pages before it ideally would.
• A high volume of pages evicted by application threads (rather than by WiredTiger's dedicated eviction threads) — a sign the database is under real memory pressure, since eviction is ideally a background process, not something happening on the application's query critical path.
• Rising read latency with no corresponding increase in CPU load — a classic indicator that reads are hitting disk instead of being served from cache.

HTI's recommendation

• On dedicated production servers, a range of 50–60% of total RAM is usually a reasonable starting point — but a starting point, not a final value.
• Always set the cache explicitly in containerized environments, regardless of MongoDB version.
• Monitor db.serverStatus().wiredTiger.cache continuously (not just at diagnostic time) — an application's working-set pattern changes over time, and cache sizing needs to track that change.
• Treat cache tuning as part of a broader performance review — alongside indexing strategy (the ESR rule) and aggregation pipeline design. A well-sized cache doesn't compensate for a missing index.

Need help sizing your environment?

We run this analysis as part of our MongoDB Health Check — cache, indexes, replication, and security, delivered as an impact-prioritized report.

Article from the MongoDB Consulting technical cluster by HTI Tecnologia — 35+ years sustaining critical databases in Brazil. Browse the full MongoDB article index.