How to Fix MongoDB Error 265 (OrphanedRangeCleanUpFailed)
You see mongodb error 265 when a shard fails to delete leftover data ranges. To fix this OrphanedRangeCleanUpFailed error, resolve replica set lag and check shard health. In a sharded cluster, the balancer moves data chunks from one shard to another. Once a move finishes, the old shard still holds a copy of that data. The database marks those old records as orphaned documents and schedules them for deletion. If the background cleanup task hits a roadblock, the engine throws code 265. Leftover d
Your coding agents run with your access.
Claude Code reaches prod with a developer's credentials, and approval prompts get clicked through. hoop.dev checks every query, masks sensitive data, and holds risky changes for a human.
You see mongodb error 265 when a shard fails to delete leftover data ranges. To fix this OrphanedRangeCleanUpFailed error, resolve replica set lag and check shard health.
In a sharded cluster, the balancer moves data chunks from one shard to another. Once a move finishes, the old shard still holds a copy of that data. The database marks those old records as orphaned documents and schedules them for deletion. If the background cleanup task hits a roadblock, the engine throws code 265. Leftover documents waste disk space and can slow down cluster maintenance over time.
Root causes of mongodb error 265 in sharded clusters
The official name for mongodb error 265 is OrphanedRangeCleanUpFailed in the database engine. Several cluster conditions can stop the shard from removing old document ranges.
First, replication lag across secondary nodes often blocks range deletion. The primary node waits for secondary nodes to acknowledge the delete writes. If a secondary falls behind or loses network contact, the cleanup task fails. Heavy write traffic on the shard can also cause write conflicts or lock timeouts.
Second, active cursors or long-running read queries can hold open references to the range. The shard waits for those reads to finish before it deletes the old records. If a query hangs for hours, the range cleanup task times out and exits.
Third, disk space shortages or hardware stalls can stop the storage engine from writing changes. When a shard steps down during an election, in-flight cleanup tasks also abort right away.
How to diagnose and fix the failure in production
Start by reading the shard server logs to find the exact collection and key range. You do not need to give engineers broad write rights to check these logs. MongoDB grants access through roles that define allowed actions down to the collection level. The built-in read role grants actions like find, listCollections, listIndexes, dbStats, and collStats. It does not allow insert, update, remove, or dropCollection actions on your data.
MongoDB Authentication & Authorization + End-to-End Encryption: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
Use a read-only role to check cluster health and collection stats first. Look at the replica set status on the affected shard to spot lagging secondary nodes. If a secondary node is unhealthy, fix its network path or disk bottleneck first. Once the replica set catches up, the shard can finish its queued delete tasks.
Next, inspect active operations to find slow queries that read from the target collection. If a stuck reporting query holds the range open, stop that specific operation. Wait for a quiet traffic window if heavy app writes are causing storage contention. In most cases, the shard retries the orphaned range cleanup on its own once healthy.
Keep your access rules tight when you run fixes on production shards. Do not hand out full cluster admin keys to everyone on the on-call team. Limit write roles to the exact task and review every command run during an incident. When inspecting collection documents, use data masking so the tool rewrites emails and phone numbers.
Inspect MongoDB wire traffic in flight
Built-in MongoDB roles govern collection access at setup time. They cannot score command risk per call or mask sensitive document values on the fly. By design, hoop.dev sits inline in the MongoDB protocol next to your server as a sidecar for your MongoDB. On every production command from mongosh, drivers, or AI agents, hoop.dev decides whether to pass, mask, block, or hold it for human review.
First, hoop.dev guardrails block bad deletes, drops, and write pipelines or hold them for approval. Next, hoop.dev data masking rewrites sensitive values in returned documents in memory and logs each decision. Explore the repo on GitHub.
Frequently asked questions
What does OrphanedRangeCleanUpFailed mean in MongoDB?
It means a shard could not delete old documents left behind after a chunk migration. The data moved to a new shard, but cleanup on the source shard failed.
Does mongodb error 265 cause data loss or corrupt my collections?
No, the live copy of that data range already lives on the destination shard. The error only means the old source shard still holds extra copies on disk.
Can I check collection stats for this error with a read-only role?
Yes, the built-in read role includes dbStats and collStats actions on non-system collections. This lets engineers inspect collection size and index details without any rights to modify data.
Related guides
In this post