Index build resource limits (maxNumActiveUserIndexBuilds, disk space)

Published reference · snapshot 2026-10-20 · skill mongodb-expert/references/index-build-resource-limits-maxnumactiveuserindexbuilds-disk-space.md

↓ Facts as markdown all context files

Source-anchored research for Index build resource limits (maxNumActiveUserIndexBuilds, disk space). Run status: COMPLETED.

These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.

How it works

One `createIndexes` command takes exactly one slot under `maxNumActiveUserIndexBuilds`, even when that command builds several indexes at once. (medium confidence) [source]
Before a `createIndexes` build registers with the coordinator, `runCreateIndexesWithCoordinator` calls `IndexBuildsCoordinator::checkDiskSpaceSufficientToStartIndexBuild`. It compares free bytes on the `storageGlobalParams.dbpath` filesystem with the threshold times 1024*1024 and throws `OutOfDiskSpace` with "available disk space of {} bytes is less than required minimum of {}" when free space is at or below the threshold. A user report shows the same message text. (medium confidence) [source]
At run time a `DiskSpaceMonitor` action aborts every active index build with `OutOfDiskSpace` when free space falls below the threshold. It logs ID 7333502 ("Attempting to kill index builds because remaining disk space is less than required minimum") once and ID 7333601 ("Index build: aborted due to insufficient disk space") for each aborted build. The docs state that a member that already voted to commit the index is not stopped. (high confidence) [source]
Before 5.1.0-rc0 the "Too many index builds running simultaneously" message could print several times for one blocked build (the reporter saw it four times within one millisecond) because it was logged inside the condition-variable predicate (SERVER-59122). Current source logs it at most once per call. On older versions, repeated lines do not mean separate blocked builds. (medium confidence) [source]
MongoDB warns that setting `indexBuildMinAvailableDiskSpaceMB` too high can needlessly block index builds when enough disk is actually free, and that raising it requires a server with enough available disk. Setting it to 0 disables the check. (low confidence) [source]
Only index builds that start from user connections on a primary wait for a slot. System-initiated builds never wait, but each one occupies a slot and can delay user builds even when fewer than N user builds are running. Secondaries use an unlimited thread pool. The source comment says this lets a secondary start as many builders as it needs, which prevents scheduling deadlocks during initial sync and oplog application. (high confidence) [source]
One createIndexes command takes one slot even when it builds several indexes. The cap counts builds, not indexes. (high confidence) [source]
A DiskSpaceMonitor job polls free space on the dbPath filesystem once per second. When free space is at or below the floor and at least one build is running, the coordinator logs ID 7333502 ('Attempting to kill index builds because remaining disk space is less than required minimum'). It then force-aborts each build. Each aborted build logs ID 7333601 ('Index build: aborted due to insufficient disk space') and increments serverStatus indexBuilds.killedDueToInsufficientDiskSpace. (high confidence) (verified as of 2026-10-20) [source]
createIndex on an empty collection still succeeds below the floor, because an empty collection does not start an index build. (low confidence) [source]
If directoryPerDB or directoryForIndexes is enabled, storesFilesInDbPath() returns false. On master, mongod then logs ID 7333400 at startup ('The index builds DiskSpaceMonitor action which periodically checks if we have enough disk space to build indexes will not run when the storage engine stores data files in different directories') and does not register the kill action. The start check is also skipped and logs ID 7333300 ('Index build: skipping available disk space check before starting index build as storage engine stores data files in different directories'). The v8.0 branch skips the start check in the same way. (high confidence) (verified as of 2026-10-20) [source]
A rolling build keeps build load off the primary. Percona lists the cost of a standard build as CPU and I/O, brief database locks and network bandwidth, and says building the traditional way near peak capacity can cause an outage. Percona and MongoDB both describe the fix as building on one non-primary member at a time. (medium confidence) [source]
Do not run a rolling index build and a replicated (simultaneous) index build at the same time. MongoDB warns this can cause broken builds and crash loops. (high confidence) [source]

How-to and procedures

To check whether a `createIndexes` call is waiting on the cap, search the mongod log for message ID 4715500 (its attributes include `numActiveIndexBuilds` and `maxNumActiveUserIndexBuilds`) and read the live setting with `db.adminCommand({ getParameter: 1, maxNumActiveUserIndexBuilds: 1 })`. (medium confidence) [source]
Use `db.currentOp()` filtered to `createIndexes` to see build progress; the `msg` field carries percent complete for the current stage. To stop a build in a replica set or sharded cluster, use `dropIndexes` or `dropIndex()`, not `killOp`. Resumable-build log lines include "Index build: wrote resumable state to disk". (medium confidence) [source]

Measurements and reference values

Atlas fixes these limits per cluster tier and does not let customers change them. `maxNumActiveUserIndexBuilds` defaults: M10-M40 = 1, M50-M60 = 2, M80 and higher (including NVMe) = 3, and the low-CPU R tiers match. `maxIndexBuildMemoryUsageMegabytes` defaults: 100 MB (M10-M20), 250 MB (M30), 400 MB (M40), 512 MB (M50-M60), 1024 MB (M80-M140), 2048 MB (M200+). (medium confidence) (verified as of 2026-10-14) [source]
`maxIndexBuildMemoryUsageMegabytes` is a double. A value >= 1.0 means megabytes. A value between 0 and 1.0 (exclusive) means a fraction of RAM, capped at 80%. mongod enforces a 50 MB floor on both forms. It can be set at startup and at runtime. (high confidence) [source]
Memory budgets add up across concurrent builds. With the default of 3 concurrent builds, total index-build memory can reach three times `maxIndexBuildMemoryUsageMegabytes` (600 MB at the default). Raising `maxNumActiveUserIndexBuilds` also increases pressure on the WiredTiger cache. (high confidence) [source]
MongoDB docs say raising `maxIndexBuildMemoryUsageMegabytes` is only needed in rare cases: many indexes in a single `createIndexes` command, or index key data sets larger than 500 GB. (high confidence) [source]
`indexBuildMinAvailableDiskSpaceMB` (new in MongoDB 7.1) sets the minimum free disk space an index build needs. Default 500 MB; 0 disables the check. A new build will not start, and a running build is cancelled, when available disk space is below it. It can be set at startup or at runtime (for example `db.adminCommand({ setParameter: 1, indexBuildMinAvailableDiskSpaceMB: 650 })`). (high confidence) [source]
A Railway user on a 500 MB volume got `MongoServerError: available disk space of 226643968 bytes is less than required minimum of 524288000` (codeName `OutOfDiskSpace`) when Mongoose `model.syncIndexes()` ran at app bootstrap (post dated 2025-10-28). 524288000 bytes is exactly 500 MiB, the default `indexBuildMinAvailableDiskSpaceMB`. The post does not state the MongoDB version; Railway's answer was to grow the volume. (medium confidence) [source]
Batching indexes into one `createIndexes` call saves slots (one slot per command) but divides the single memory budget across them (200 MB over 10 indexes is 20 MB each), so large batches reach the `_tmp` spill threshold sooner. (medium confidence) [source]
No MongoDB or Percona page read gives a formula for the temporary disk an index build needs; the docs say only that builds use memory plus temporary files. A third-party page (adhdecode, 2026-04-18) asserts index builds "can require 2x-3x the final index size in temporary space" with no source or measurement. (low confidence) (verified as of 2026-10-20) [source]
maxIndexBuildMemoryUsageMegabytes accepts megabytes or a fraction of RAM. A value >= 1.0 means megabytes. A value between 0 and 1.0 (exclusive) means a fraction of RAM, capped at 80%. A 50 MB floor applies to both forms. You can change it at startup or at runtime on self-managed servers. Atlas does not allow changing it. (medium confidence) (verified as of 2026-10-14) [source]
indexBuildMinAvailableDiskSpaceMB (new in 7.1) sets a free-disk floor for index builds. The default is 500 MB. Valid values run from 0 to 8796093022207 MB (about 8 TB); 0 disables the floor. You can change it at startup or at runtime. If free space is at or below the floor, a new build does not start and a running build is cancelled. The docs warn that a value set too high blocks builds that would have fit. (high confidence) [source]
On Atlas the limits are fixed per cluster tier. maxNumActiveUserIndexBuilds is 1 on M10-M40, 2 on M50-M60 and 3 on M80 and higher (including NVMe variants); the low-CPU R tiers match their M tiers. maxIndexBuildMemoryUsageMegabytes is 100 MB on M10-M20, 250 MB on M30, 400 MB on M40, 512 MB on M50-M60, 1024 MB on M80-M140 and 2048 MB on M200 and above. (medium confidence) (verified as of 2026-10-14) [source]
MongoDB says to prefer the default simultaneous build. Use a rolling index build only when average CPU utilization exceeds (N-1)/N - 10% (N is the number of CPU threads available to mongod) or the WiredTiger cache fill ratio regularly exceeds 90%. A rolling build hides at most one member at a time, needs at least one election, lowers cluster resiliency and lengthens the build. On Atlas, the alternative is to scale the cluster up temporarily, which is billed. (high confidence) [source]
Raising maxNumActiveUserIndexBuilds trades throughput for load. MongoDB says more concurrent builds increase pressure on the WiredTiger cache, and each extra build can add up to maxIndexBuildMemoryUsageMegabytes of sorter memory. MongoDB also calls raising the memory setting necessary only in rare cases, such as many indexes in one command or more than 500 GB of index key data. (medium confidence) [source]

Problems, failure modes and limitations

`maxNumActiveUserIndexBuilds` caps how many user-initiated index builds one mongod runs at once. The default is 3, the IDL validator requires a value >= 0, and it can be set at startup or at runtime with `setParameter` (for example `db.adminCommand({ setParameter: 1, maxNumActiveUserIndexBuilds: 4 })`). It is a global limit across all collections. (high confidence) [source]
When the cap is reached, the server blocks further user index builds until the active count drops below the limit or the operation is interrupted. The blocked build logs message ID 4715500: "Too many index builds running simultaneously, waiting until the number of active index builds is below the threshold." (high confidence) [source]
System index builds are not limited by `maxNumActiveUserIndexBuilds` and never wait, but each one still occupies a slot. A system build can therefore delay user builds even when fewer user builds than the limit are running. The source comment reads: "System index builds have no limit and never wait, but do consume a slot." (high confidence) [source]
`maxIndexBuildMemoryUsageMegabytes` defaults to 200 MB per `createIndexes` command in self-managed deployments. The command splits that budget equally across the indexes it builds (10 indexes get 20 MB each). The memory is separate from the WiredTiger cache. When a build reaches its limit, MongoDB writes temporary files to the `_tmp` subdirectory under `--dbpath`. Percona's sample build-start log line shows `"maxTemporaryMemoryUsageMB":200`. (high confidence) [source]
Before the 7.1 guard, a full disk during the external sort failed the build with a raw filesystem error. SERVER-56424 (reported on 4.4.5) logged `error writing to file ".../_tmp/extsort-index.1227": errno:28 No space left on device` (code 16821, sorter.cpp), then `Index build failed`, then an invariant failure `Unnexpected error code during index build cleanup`. The ticket only improved that cleanup message (fixed in 4.4.8, 5.0.0-rc3, 5.1.0-rc0). The 9.0 docs state that before 7.1 an index build is not stopped for insufficient disk space. (medium confidence) [source]
The IDL validator for `maxNumActiveUserIndexBuilds` is `gte: 0`, and the wait predicate admits a user build only while the active count is below the limit. A value of 0 would therefore make every user-connection build wait until interrupted. This is an inference from source and was not tested. (low confidence) [source]
MongoDB recommends building indexes in a maintenance window with stopped or reduced writes, because builds under heavy write load slow writes and run longer. A third-party blog (OneUptime, 2026-03-31) goes further and advises 1 concurrent build in production to protect query latency and 2-3 in maintenance windows. That tuning is the author's opinion, not a vendor recommendation. (medium confidence) [source]
SERVER-47155 introduced the cap in 4.4 (fix versions 4.4.0-rc0 and 4.7.0). Its title is 'Limit the number of simultaneous index builds running from user connections to 3'. (medium confidence) [source]
Index build memory is budgeted apart from the cap. On self-managed servers, maxIndexBuildMemoryUsageMegabytes defaults to 200 MB per createIndexes command, split equally among the indexes that command builds. When a build reaches the limit, the external sorter spills sorted keys to temporary files in the _tmp subdirectory of dbPath. With the default cap of 3, worst-case sorter memory is 3 x 200 MB = 600 MB. This memory is separate from the WiredTiger cache. (high confidence) [source]
The disk abort works only before the member votes to commit. After the vote, the monitor's attempt fails and logs ID 7617000 ('Index build: cannot force abort'). The build then completes and the kill counter does not change. The docs add that for other index build errors after the vote, a secondary cannot request an abort and crashes, as in 7.0 and earlier. (high confidence) [source]
Before the 7.1 behavior, no floor stops a build, so a build runs until the filesystem returns ENOSPC. In 4.4.5 this logged error 16821 ('error writing to file ... errno:28 No space left on device') from the external sorter, then invariant failure ID 23081 ('Unnexpected error code during index build cleanup') during cleanup. SERVER-56424 only improved the invariant message, in 4.4.8, 5.0.0-rc3 and 5.1.0-rc0. (medium confidence) [source]
Atlas customers cannot tune these limits. The parameters page says Atlas uses cluster-tier defaults that you cannot change. The index-creation page says you cannot modify maxIndexBuildMemoryUsageMegabytes on Atlas. The setParameter command is not supported on Atlas clusters. (high confidence) [source]

Comparisons and alternatives

The wait in `IndexBuildsCoordinatorMongod::_startIndexBuild` is gated on `opCtx->getClient()->isFromUserConnection()`, not on primary versus secondary role. A secondary that starts a build from a replicated oplog entry is not a user connection, so this cap should not make that build wait. This is an inference from source; the docs do not state it. SERVER-47155 scopes the limit to builds that users start on primaries. (low confidence) [source]
SERVER-47155 introduced the limit of three concurrent user index builds and the `maxNumActiveUserIndexBuilds` setParameter (created 2020-03-27, resolved 2020-04-02, fix versions 4.4.0-rc0 and 4.7.0). SERVER-49948 proposed adding the setParameter to 4.2 instead of backporting SERVER-47155 and was closed Won't Do on 2020-07-29. (high confidence) [source]
When the cap is reached, the server blocks the next user index build instead of failing it. The createIndexes caller waits until the active count drops below the cap or the operation is interrupted. The server logs ID 4715500 when a build blocks: 'Too many index builds running simultaneously, waiting until the number of active index builds is below the threshold'. (high confidence) [source]
To avoid waiting for a slot, build several indexes with one createIndexes command, which uses one slot. The trade-off is memory: the 200 MB default budget is split equally across the command's indexes, so each index has a smaller in-memory budget before it spills to _tmp. (medium confidence) [source]

Facts and statements

The index build thread pool has no thread cap: `makeDefaultThreadPoolOptions` sets `.maxThreads = ThreadPool::Options::kUnlimited` and the comment says primary and secondary both get an unlimited pool. The `maxNumActiveUserIndexBuilds` wait in `_startIndexBuild` is what limits concurrent user builds. (low confidence) [source]
`serverStatus` reports `indexBuilds.killedDueToInsufficientDiskSpace`, the number of builds ended for low disk space since the last restart, next to `indexBuilds.total` and `indexBuilds.failedDueToDataCorruption`. The coordinator increments the kill counter for each build the disk guard aborts. (high confidence) [source]
A build touches disk in more than one place: the external sorter's spill files under `<dbpath>/_tmp`, a side-writes table that holds keys from writes made during the build, a constraint violation table, and the finished index. The collection scan generates a key for every document and dumps it into the external sorter, which keeps keys in memory or in temporary disk files. (medium confidence) [source]
Before 4.4.2 and 4.7.0, concurrent `createIndexes` calls waiting for a free slot held write tickets (global lock in IX mode) while IndexBuildsCoordinator worker threads needed write tickets. That circular wait could block every write on a primary or standalone. SERVER-48617 is titled "Concurrent 'createIndexes' can block all write operations on a primary and standalone by exhausting write tickets". (medium confidence) [source]
A build that waits for its commit quorum keeps running, so it should keep its `maxNumActiveUserIndexBuilds` slot until the build ends (the scheduled pool task releases the slot at build end). With the default commit quorum `votingMembers`, an unreachable voting member can hang builds, so enough hung builds could starve later user builds. This is an inference from the docs and source; neither states it. (low confidence) [source]
The historical workaround for a small `dbpath` volume is to symlink `<dbpath>/_tmp` to a larger volume (SERVER-12115, about `mongod --repair`, closed Won't Fix in 2018). The 7.1 guard reads free space of the `dbpath` filesystem only, so a symlinked `_tmp` volume would not be what the guard measures. The second point is an inference. (low confidence) [source]
MongoDB 8.2 (also 8.0.13 and 7.0.26) adds separate memory knobs for index builds during initial sync: `initialSyncIndexBuildMemoryPercentage` (default 10.0, range 0.0-80.0), `initialSyncIndexBuildMemoryMinMB` (default 200, range 50-10000000) and `initialSyncIndexBuildMemoryMaxMB` (default 16384, range 50-10000000). (low confidence) (verified as of 2026-10-14) [source]
On MongoDB master, primary-driven index builds sit behind `featureFlagPrimaryDrivenIndexBuilds` (default false, FCV-gated) and add disk-write throttles: `primaryDrivenIndexBuildScanPhaseContainerWriteMBperSec` and `primaryDrivenIndexBuildBulkLoadPhaseContainerWriteMBperSec` (both default 0, meaning unthrottled), plus `primaryDrivenIndexBuildIndexTableCleanupBatchBytes` (default 4 MiB). The 9.0 parameters page does not list them. (low confidence) (verified as of 2026-10-20) [source]
maxNumActiveUserIndexBuilds caps concurrent index builds on a self-managed server. The default is 3. The cap is global across all collections. You can change it at startup or at runtime with setParameter. The IDL validator accepts any integer >= 0. (high confidence) [source]
Secondaries enforce the same floor. A secondary below the floor that has not yet voted asks the primary to abort the build with voteAbortIndexBuild. The primary's build ends with IndexBuildAborted, the secondary does not crash, and both nodes keep only the _id_ index. (high confidence) [source]
In the default two-phase protocol, every data-bearing member scans its own data and spills to its own unreplicated temp files under dbPath/_tmp. It then bulk-loads the sorted keys into the WiredTiger index. Every member therefore needs disk headroom for the build, not only the primary. (medium confidence) [source]
Primary-driven index builds would change where spill space goes. They build the index only on the primary and spill sorted keys into a replicated storage-engine table, so secondaries receive the keys through the oplog. Commit quorum does not apply to them. On 2026-10-20 featureFlagPrimaryDrivenIndexBuilds defaults to false on master, so two-phase builds remain the default. (medium confidence) (verified as of 2026-10-20) [source]
If free space is at or below the floor, createIndexes on a populated collection fails with OutOfDiskSpace and the message 'available disk space of <n> bytes is less than required minimum of <m>'. Both numbers are in bytes, although the parameter is in MB. (high confidence) [source]
On the v8.0 branch, the low-disk kill action returns early and logs ID 6826200 ('Index build: disk space monitor detected we're low on storage space but 'featureFlagIndexBuildGracefulErrorHandling' is disabled. Ignoring it') unless that flag is enabled. The flag has default true and version 7.1, so it needs FCV 7.1 or later. A cluster running 8.0 binaries at FCV 7.0 therefore does not abort builds on low disk. (medium confidence) (verified as of 2026-10-20) [source]
Before the fix in 4.4.2 and 4.7.0, a createIndexes call blocked on the cap could hold a write ticket (global lock in IX mode) while it waited. Enough blocked callers exhausted write tickets and stalled all writes on the primary (SERVER-48617). In current source, the lock guard for the primary-state check that precedes the wait is scoped so it is released before the wait. (medium confidence) [source]
A createIndexes call that seems hung may be waiting for a slot. Search the log for ID 4715500. The entry carries numActiveIndexBuilds, maxNumActiveUserIndexBuilds, indexSpecs, buildUUID and collectionUUID. Before 5.1.0-rc0, one blocked build could print the message several times, even within the same millisecond (SERVER-59122). The code now logs it once per blocked build. (high confidence) [source]
Change the limits with db.adminCommand({ setParameter: 1, maxNumActiveUserIndexBuilds: 4 }) at runtime, or with mongod --setParameter at startup. indexBuildMinAvailableDiskSpaceMB and maxIndexBuildMemoryUsageMegabytes use the same two routes. The docs example sets indexBuildMinAvailableDiskSpaceMB to 650. (high confidence) [source]
Three counters show the disk guard at work. serverStatus().indexBuilds.killedDueToInsufficientDiskSpace counts aborted builds. serverStatus().metrics.diskSpaceMonitor.passes and .tookAction count monitor polls and actions taken. db.currentOp() shows in-progress builds with a percent-complete msg field. (medium confidence) (verified as of 2026-10-20) [source]
Percona says a rolling build needs an oplog window at least as long as the build. For a 2-hour build, keep the window at 2 hours or more, preferably a bit more. (low confidence) [source]
Setting maxNumActiveUserIndexBuilds to 0 passes the validator (gte: 0). The admission test is _numActiveIndexBuilds < maxNumActiveUserIndexBuilds, which can never be true at 0. Every createIndexes from a user connection that needs a build then waits until you raise the value or interrupt the operation. This reading comes from the source; the docs do not describe it. (low confidence) [source]

Children

Atlas index build tier defaults (frontier)
Atlas tier-fixed index build limits (frontier)
Commit quorum and the vote-to-commit point of no return (frontier)
DiskSpaceMonitor and low-disk index build abort (7.1+) (frontier)
External sorter spill files and the _tmp directory (frontier)
Index build commit quorum and hung builds (frontier)
Index build memory limit and external sorter spill (maxIndexBuildMemoryUsageMegabytes) (frontier)
Initial sync index build memory limits (frontier)
Primary-driven index builds (spill to a replicated table) (frontier)
Primary-driven index builds and write-rate throttles (frontier)
Rolling index builds as a resource-isolation alternative (frontier)
Rolling index builds as a resource-limited alternative (frontier)
WiredTiger cache pressure and write tickets during index builds (frontier)
serverStatus indexBuilds metrics and index build observability (frontier)

Frontier under this node: Atlas index build tier defaults, Atlas tier-fixed index build limits, Commit quorum and the vote-to-commit point of no return, DiskSpaceMonitor and low-disk index build abort (7.1+), External sorter spill files and the _tmp directory, Index build commit quorum and hung builds, Index build memory limit and external sorter spill (maxIndexBuildMemoryUsageMegabytes), Initial sync index build memory limits, Primary-driven index builds (spill to a replicated table), Primary-driven index builds and write-rate throttles, Rolling index builds as a resource-isolation alternative, Rolling index builds as a resource-limited alternative, WiredTiger cache pressure and write tickets during index builds, serverStatus indexBuilds metrics and index build observability

← the whole tree · 3D view· how to read this page