Orphaned documents and range deletion
Parent: Covered queries on sharded collections · Published reference · snapshot 2026-10-23 · skill mongodb-cohort-74cd39f19180
↓ Facts as markdownall context files
Source-anchored research for Orphaned documents and range deletion. 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
- MongoDB issue SERVER-130130 reports that recipient-side orphan bookkeeping can drift below the true count when a migration delete entry matches no recipient document. Jira lists the issue as unresolved for affected 6.0.0, 7.0.0, and 8.0.0 versions; it describes a bookkeeping defect, not direct user-data loss. (low confidence) (verified as of 2026-10-13) [source]
- Range deletion follows the ownership metadata handoff asynchronously. MongoDB waits for relevant open cursors before deleting the source copy, and the balancer can start a later range migration while an earlier delete phase is still pending. Open cursors can delay cleanup, and large range deletions can cause cache and I/O stress. Current MongoDB documentation says cleanup is resilient to a replica-set primary crash or restart. (high confidence) (verified as of 2026-10-23) [source]
Problems, failure modes and limitations
- The current MongoDB manual marks cleanupOrphaned deprecated starting in 8.0. The command runs on a shard primary, waits for orphan cleanup across the namespace, and does not directly start deletion; it must not run on mongos. (high confidence) (verified as of 2026-10-23) [source]
- Range cleanup can wait on open cursors: the current balancer procedure deletes the source copy only after open cursors on the range are gone. A MongoDB 3.4 forum response explains that an already-being-processed-for-deletion response typically means a query still holds a cursor; the response alone does not establish a failure. (medium confidence) [source]
- The MongoDB 9.0 manual marks cleanupOrphaned deprecated since 8.0 and says it waits for all orphaned documents in the namespace to be cleaned from a majority of the shard's replica-set members; it does not delete them directly. Alibaba's 2026 upgrade guide says MongoDB 4.4 introduced automatic migration recovery and that cleanupOrphaned can verify the background cleanup. Apply version-specific guidance before using older cleanup loops. (high confidence) (verified as of 2026-10-23) [source]
Facts and statements
- A range migration updates ownership metadata before the source shard deletes its old copy; the balancer deletes that copy after no open cursors remain. These leftover source copies are orphaned documents and consume disk while range deletion is pending. (high confidence) [source]
- MongoDB 8.2 documentation sets orphanCleanupDelaySecs to 3600 seconds by default and terminateSecondaryReadsOnOrphanCleanup to true. The source shard waits for existing primary reads and then the delay before deleting orphans; secondaries terminate reads that began before migration commit. If that termination setting is disabled, a secondary read may silently miss moved documents; long-running reads may otherwise receive QueryPlanKilled and need to resume. (high confidence) (verified as of 2026-10-23) [source]
- One MongoDB 3.4 operator reported cleanupOrphaned running for three days across more than 100 shards, with rangeDeleter logs often showing zero deletions. This is a single 2018 report, not an expected duration for current versions. (low confidence) [source]
- MongoDB issue SERVER-78703 documents a historical count behavior where numOrphans stayed at its pre-deletion value until range deletion finished, so the tracked count could exceed the remaining documents during cleanup. The issue lists fixes in 7.0.0-rc7 and 7.1.0-rc0. (low confidence) [source]
- MongoDB defines orphaned documents as documents on a shard that also exist in chunks on other shards. They can remain on a former donor while range cleanup is incomplete after ownership moves. (high confidence) [source]
- Starting in MongoDB 8.2, long-running secondary reads can be terminated before orphan deletion to avoid missing documents; the default orphanCleanupDelaySecs also increased from 900 seconds to 3600 seconds. Applications with long-running secondary reads should account for version-specific termination behavior during chunk migrations. (high confidence) (verified as of 2026-10-23) [source]
Children
- Range deletion task lifecycle (frontier)
- Orphan cleanup wait semantics (frontier)
- Orphan-count metadata (frontier)
Frontier under this node: Orphan cleanup wait semantics, Orphan-count metadata, Range deletion task lifecycle