Balancer, chunk migration and jumbo chunk remediation
Parent: Shard Key Design and Resharding as Cost Levers · Published reference · snapshot 2026-10-31
↓ Facts as markdownall context files
Source-anchored research for Balancer, chunk migration and jumbo chunk remediation. 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
- Manually clearing a jumbo flag does not repair an oversized indivisible range. MongoDB can mark it jumbo again on a subsequent move attempt; use clearJumboFlag only when the preferred split remedy is inapplicable. (medium confidence) [source]
- MongoDB master balancer_policy.cpp skips jumbo-flagged chunks when draining a shard and during normal selection. A shard-removal plan can therefore stall until those chunks receive manual remediation. Master is implementation evidence, not a guarantee for every released version. (medium confidence) (verified as of 2026-10-30) [source]
- Choose a balancing window with enough time to finish the required movement. Off-peak windows reduce contention, but short windows prolong shard addition or removal because migration resumes in later windows. (high confidence) (verified as of 2026-08-20) [source]
- Alibaba warns that leaving attemptToBalanceJumboChunks enabled after moving an indivisible oversized chunk can cause repeated back-and-forth migrations under data-size balancing, adding transfer and orphan-cleanup overhead. Its remediation procedure restores the setting after the required move. (low confidence) (verified as of 2026-08-20) [source]
- Source-side range deletion is asynchronous and can create cache and I/O stress after migration commits. Upstream documentation suggests evaluating resharding for bulk redistribution because it avoids this range-cleanup phase; this is not a guarantee that every resharding operation is cheaper. (low confidence) (verified as of 2026-10-30) [source]
- SERVER-132762 reports that automatic force-jumbo migration with attemptToBalanceJumboChunks:true can hit a duplicate-_id race when concurrent shard-key updates cause an index scan to clone a document twice. The ticket last updated August 24, 2026 lists no affected or fixed versions; verify the deployed release before selecting this workaround. (low confidence) (verified as of 2026-08-24) [source]
Measurements and reference values
- The modern balancer compares collection data sizes across shards. Its documented trigger is a difference of at least three configured range sizes: 384 MB with a 128 MB range size. Unequal chunk counts alone do not establish imbalance. (high confidence) (verified as of 2026-10-30) [source]
- Percona documented oversized chunks without expected jumbo detection in a MongoDB 3.6 incident. Its 2021 script uses historical config.chunks namespace fields and a 64 MB threshold; treat it as historical diagnostic evidence, not a current-version runbook. (low confidence) [source]
Problems, failure modes and limitations
- A high-frequency shard-key value can produce an oversized indivisible chunk. The balancer cannot split documents sharing that complete key value across chunks, which can preserve a resource hotspot despite spare capacity elsewhere. (high confidence) [source]
- Percona reported a MongoDB 3.6 production case with slow moves of oversized chunks that had escaped detection. Multiple mongos routers and router restarts could undermine the old router-local splitter statistics. This is historical evidence, not current autosplitter behavior. (low confidence) [source]
- Cost implication (inference): repairing indivisible hot ranges and reducing recurring migrations can recover useful capacity before adding infrastructure. Data balance alone cannot establish balanced query or write load, and these sources provide no general percentage cost saving. (medium confidence) [source]
Comparisons and alternatives
- Schedule balancing during quieter hours to reduce competition with application traffic; disabling it indefinitely can allow skew to persist. This shifts migration work in time rather than eliminating it. (high confidence) [source]
Facts and statements
- For ordinary upstream range migrations, each shard participates in at most one migration at a time, limiting an n-shard cluster to floor(n/2) concurrent migrations. This bounds how quickly newly added capacity can receive data. (high confidence) (verified as of 2026-10-30) [source]
- For a divisible jumbo chunk, the preferred manual remedy is sh.splitAt() or sh.splitFind(); a successful split clears the jumbo flag. (high confidence) (verified as of 2026-10-30) [source]
- Appending sufficiently discriminating suffix fields with refineCollectionShardKey can make an indivisible jumbo range divisible. Refinement itself does not immediately redistribute chunks; splitting and migration must still follow. Resharding with a better-distributed key is another remedy. (high confidence) (verified as of 2026-10-30) [source]
- The documented default migration document-count ceiling is twice configured range size divided by collection avgObjSize; a movable sub-range can be migrated instead. The collection average makes the check sensitive to document-size distribution. (high confidence) (verified as of 2026-10-30) [source]
- attemptToBalanceJumboChunks permits oversized moves only for chunks without the jumbo label. Manual moveRange or moveChunk with forceJumbo can override the size restriction for labeled or unlabeled ranges. (high confidence) (verified as of 2026-10-30) [source]
- Diagnose stalled balancing using balancer state, balancerStatus, sh.status(true), and config-server/shard logs. Check migration errors, long-running operations, replication lag and disk capacity before attributing all skew to shard-key design. (low confidence) [source]
- Balancer migrations consume source reads, destination writes and network bandwidth. Inference for cost planning: frequent redistribution competes with application work, so evaluate migration load alongside steady-state capacity; these sources do not establish a universal monetary saving. (high confidence) [source]
- Diagnose stalled balancing by checking sh.getBalancerState(), balancerStatus, sh.status(true), and config-server and shard logs. Look for migration failures, replication lag, lock contention and disk pressure before assuming a shard-key defect. (medium confidence) (verified as of 2026-10-30) [source]
- A jumbo chunk can prevent balancing and shard draining. Distinguish a divisible oversized range from an indivisible range containing a single shard-key value; the latter needs a remedy that changes divisibility or deliberately moves the oversized unit. (high confidence) [source]
- Clearing the jumbo flag does not shrink the data or fix a repeated shard-key value. The official procedure warns that an oversized chunk can be marked jumbo again on a later migration attempt; Alibaba likewise says shrinking data does not automatically clear the flag. (high confidence) (verified as of 2026-10-30) [source]
- The upstream document-count migration guard uses twice the configured range size divided by collection average document size. attemptToBalanceJumboChunks can permit oversized chunks that are not labeled jumbo; manual forceJumbo can also move labeled chunks. (low confidence) (verified as of 2026-10-30) [source]
- Alibaba distinguishes automatic oversized migration after clearing the flag from manual moveChunk with forceJumbo:true. Its guidance warns that the manual option can block source-shard collection writes throughout copying, potentially for hours, and recommends off-peak operation with support assistance. This is provider guidance, not a measured duration guarantee. (low confidence) (verified as of 2026-08-20) [source]
Children
- Migration critical sections and application latency (frontier)
- Orphan cleanup and range-deletion resource budgeting (frontier)
- Jumbo flags versus oversized ranges (frontier)
- Migration critical sections and write blocking (frontier)
- Oversized ranges versus jumbo metadata flags (frontier)
- Indivisible ranges and shard-key refinement (frontier)
- Asynchronous range deletion and orphan cleanup (frontier)
- Balancer windows and migration progress estimation (frontier)
Frontier under this node: Asynchronous range deletion and orphan cleanup, Balancer windows and migration progress estimation, Indivisible ranges and shard-key refinement, Jumbo flags versus oversized ranges, Migration critical sections and application latency, Migration critical sections and write blocking, Orphan cleanup and range-deletion resource budgeting, Oversized ranges versus jumbo metadata flags