# Index build memory limit and external sorter spill (maxIndexBuildMemoryUsageMegabytes) > Source-anchored research for Index build memory limit and external sorter spill (maxIndexBuildMemoryUsageMegabytes). Run status: COMPLETED. Parent: [Index build resource limits (maxNumActiveUserIndexBuilds, disk space)](https://llms-explorer.com/tree/index-build-resource-limits-maxnumactiveuserindexbuilds-disk-space/) · 6 facets · 15 facts · page: https://llms-explorer.com/tree/index-build-memory-limit-and-external-sorter-spill-maxindexbuildmemoryusagemegabytes/ ## Definitions - Setting maxIndexBuildMemoryUsageMegabytes is an index-construction control. Its documented key-generation and external-sort budget should not be treated as a query-execution sort budget or as a control for SORT_MERGE planning and $in expansion. (medium confidence) — [source](https://www.mongodb.com/docs/v8.0/reference/parameters/) ## How it works - During conventional two-phase index builds, MongoDB generates keys during a collection scan, sorts them externally, and bulk-loads sorted keys into the index. When the sorter reaches its memory budget it writes sorted runs to temporary files under dbpath/_tmp; spilling permits builds larger than RAM. (high confidence) — [source](https://github.com/mongodb/mongo/blob/master/src/mongo/db/index_builds/README.md) - Small per-index budgets can cause frequent spills and intermediate merges. MongoDB issue SERVER-114768 also reports cases where increasing index-build memory increased initial-sync build time when spilling remained necessary; more memory is not an unconditional performance improvement. Benchmark the actual workload. (medium confidence) (verified as of 2025-12-09) — [source](https://jira.mongodb.org/browse/SERVER-114768) ## Measurements and reference values - For self-hosted createIndexes, the documented default is 200 MB per command, shared equally among the indexes in that command. Ten indexes in one command therefore receive 20 MB each under that default; spill files are placed under dbpath/_tmp. (high confidence) (verified as of 2026-10-30) — [source](https://www.mongodb.com/docs/manual/reference/command/createIndexes.md) - The index-build memory budget is separate from the WiredTiger cache. Concurrent createIndexes commands multiply the build budgets: with maxNumActiveUserIndexBuilds=3 and a 200 MB command budget, their documented aggregate allowance can reach 600 MB. This calculation is not a cap on total mongod or container memory. (high confidence) (verified as of 2026-10-30) — [source](https://www.mongodb.com/docs/v8.0/reference/parameters/) - SERVER-106589 records separate initial-sync index-build memory tuning: 10% of available RAM by default, at least 200 MB and at most 16 GB, controlled by initialSyncIndexBuildMemoryPercentage, initialSyncIndexBuildMemoryMinMB, and initialSyncIndexBuildMemoryMaxMB. Listed fix versions are 8.2.0-rc0, 8.0.13, and 7.0.26; do not generalize the older universal-budget wording across patched initial sync. (low confidence) (verified as of 2026-05-24) — [source](https://jira.mongodb.org/browse/SERVER-106589) - Alibaba Cloud Apsara Stack V3.20.0 documentation dated 2026-04-23 lists setParameter.maxIndexBuildMemoryUsageMegabytes with default 200 MB and an allowed 50–200 MB range for its MongoDB 5.0–7.0 service entries. These are service-specific bounds, not upstream MongoDB bounds. (low confidence) (verified as of 2026-10-31) — [source](https://apsarastackdocument.oss-cn-hangzhou.aliyuncs.com/%E5%9B%BD%E9%99%85%E7%89%88%E6%96%87%E6%A1%A3/v3.20.0%E7%89%88%E6%9C%AC%E6%96%87%E6%A1%A3/%E4%BA%91%E6%95%B0%E6%8D%AE%E5%BA%93MongoDB/%E9%98%BF%E9%87%8C%E4%BA%91%20%E4%B8%93%E6%9C%89%E4%BA%91%20V3.20.0%20%E4%BA%91%E6%95%B0%E6%8D%AE%E5%BA%93%20MongoDB%20%E7%89%88%20%E7%94%A8%E6%88%B7%E6%8C%87%E5%8D%97%2020260423.pdf) - The MongoDB design README says spill-run iterator memory is deducted from the sorter budget and controlled by maxIteratorsMemoryUsagePercentage, with a minimum sufficient for one iterator and a maximum of 1 MB. This is implementation documentation for the inspected master snapshot, not a guarantee for every released patch. (low confidence) (verified as of 2026-10-30) — [source](https://github.com/mongodb/mongo/blob/master/src/mongo/db/index_builds/README.md) ## Problems, failure modes and limitations - A Percona Operator user running percona-server-mongodb:4.4.16-16 reported resolving a slow index build by increasing maxIndexBuildMemoryUsageMegabytes and pod memory; replies cautioned that a 250 GB build budget on a 256 GB host leaves little RAM for other consumers. This is a historical operational anecdote, not a recommended production budget. (low confidence) (verified as of 2023-08-03) — [source](https://forums.percona.com/t/the-operator-is-not-updating-the-config-until-the-pvc-removed-and-recreated/23614) - The current createIndexes documentation says Atlas index-build memory and concurrency defaults vary by cluster tier and that users cannot modify maxIndexBuildMemoryUsageMegabytes on Atlas; self-hosted tuning recipes therefore require a deployment check. (high confidence) (verified as of 2026-10-30) — [source](https://www.mongodb.com/docs/manual/reference/command/createIndexes.md) ## Comparisons and alternatives - A Percona operator incident records OOM kills during large index builds and warns that allocating nearly all host memory to index construction leaves too little for other consumers. An independent author describes overlapping index-build, cache, connection, and aggregation memory pressure. Together these support budgeting container headroom rather than sizing only the sorter allowance; neither anecdote establishes a portable extra-memory constant. (medium confidence) — [source](https://forums.percona.com/t/the-operator-is-not-updating-the-config-until-the-pvc-removed-and-recreated/23614) ## Facts and statements - In the MongoDB 8.0 parameter documentation, changing maxIndexBuildMemoryUsageMegabytes does not affect a build that has already started its collection scan. SERVER-130149 proposes adoption of increases at spill boundaries; its source snapshot still shows an unresolved improvement, not a released fix. (high confidence) (verified as of 2026-10-26) — [source](https://www.mongodb.com/docs/v8.0/reference/parameters/) - SERVER-102428 records an initial-sync bug in which secondary indexes split one memory budget while the _id index received another full budget. The issue lists fixes in 8.2.0-rc0, 8.1.2, 8.0.13, and 7.0.26; apparent memory overruns need patch-version context. (low confidence) (verified as of 2025-09-29) — [source](https://jira.mongodb.org/browse/SERVER-102428) - serverStatus.indexBulkBuilder exposes spilledRanges, bytesSpilled, bytesSpilledUncompressed, and external-sort file-handle counters for diagnosing index-build spills. The spill-count and byte metrics were added in 6.0.4; memUsage, bytesSorted, and numSorted were added in 6.3. (low confidence) (verified as of 2026-10-14) — [source](https://www.mongodb.com/docs/manual/reference/command/serverStatus.md) - serverStatus.indexBulkBuilder exposes spilledRanges, bytesSpilled, bytesSpilledUncompressed, and memUsage for diagnosing index-build sorter activity. spilledRanges counts spills; bytesSpilled measures disk bytes, while memUsage measures current memory allocated for building indexes. (low confidence) — [source](https://www.mongodb.com/docs/v8.0/reference/command/serverstatus/)