How to Fix MongoDB Error 250 (StaleChunkHistory)

Published
Length
3 min read

Luis Felipe Dias

All posts

You get mongodb error 250 when a snapshot read hits outdated shard chunk history. You can fix it by retrying the read with a fresh snapshot timestamp. This failure uses the official name StaleChunkHistory in the database engine. It belongs to the SnapshotError category in sharded deployments. When data moves across shards, the cluster keeps a log of chunk changes. If your query reads from a point in time before the kept history, it fails. Teams see this issue during long transactions or slow an

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 get mongodb error 250 when a snapshot read hits outdated shard chunk history. You can fix it by retrying the read with a fresh snapshot timestamp.

This failure uses the official name StaleChunkHistory in the database engine. It belongs to the SnapshotError category in sharded deployments. When data moves across shards, the cluster keeps a log of chunk changes. If your query reads from a point in time before the kept history, it fails. Teams see this issue during long transactions or slow analytical queries. You do not need to restart nodes to clear this state. Instead, you must adjust how your app handles long reads and chunk moves.

Root causes of mongodb error 250 in sharded clusters

Sharded clusters split large collections into smaller chunks across multiple servers. The balancer moves these chunks in the background to keep storage even. When a chunk moves, each shard records the change in its local history. Snapshot reads let an app read data from a fixed point in time. The shard checks its chunk history to serve the right data for that moment.

Still, shards do not keep chunk history forever. The storage engine cleans up old history entries to save disk space and memory. If a query asks for a timestamp older than the earliest saved history, the shard stops. It returns code 250 and marks the operation with the StaleChunkHistory label. Because this is a SnapshotError, the database aborts the current read or transaction right away.

Two things make this error happen more often in busy systems. First, a query or transaction might run for way too long. By the time it reads from a second shard, the snapshot timestamp is too old. Second, heavy write loads or frequent chunk splits can push old history out faster. Network delays between the query router and the shards can also age the snapshot.

How to diagnose and fix StaleChunkHistory in production

Start by checking your app logs to find which queries trigger the failure. Look for slow reads or multi-document transactions that keeps the session active for a long time. You can also check database stats and collection stats to spot heavy activity. When engineers check production shards, they should use safe, limited permissions. MongoDB grants access through role-based rules that work down to the collection level. Give your team the built-in read role so they can run find and stats actions. This role blocks insert, update, remove, and drop actions on production data.

The fastest way to fix code 250 is to retry the failed transaction. Because StaleChunkHistory is a SnapshotError, a new transaction gets a fresh timestamp. The new timestamp falls within the active chunk history window, so the read succeeds. Most modern database drivers can retry transient transaction errors if you use their callback APIs. Make sure your app logic wraps snapshot reads inside a clean retry loop.

MongoDB Authentication & Authorization + End-to-End Encryption: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Next, shorten the run time of your snapshot queries and transactions. Break large analytical reads into smaller batches that finish in a few seconds. Add missing indexes so the shard does not scan whole collections during a snapshot read. If a teammate must add an index, grant the readWrite role only for that task. If batch jobs still hit the error during peak hours, schedule them for quiet times. Less chunk movement during those hours means the shard history stays valid much longer.

Preventing recurring snapshot errors at scale

Good app design prevents most StaleChunkHistory errors before they reach production users. Avoid holding transactions open while your app waits for outside network calls. Run all math and API checks before you start the database transaction. Keep the transaction focused only on fast database reads and writes.

Also review whether every query really needs point-in-time snapshot isolation. Simple status checks and single-document lookups rarely need a cluster-wide snapshot. Saving snapshot reads for true multi-step reports reduces load on the shard history log. Your cluster will run faster and return far fewer snapshot errors under heavy load.

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 StaleChunkHistory mean in plain terms?

It means your query asked for a past view of data that moved across shards. The shard already erased the routing history for that old timestamp, so it cannot answer.

Does mongodb error 250 mean my shard data is corrupt?

No, your stored data is safe and intact. The error only means the temporary history window for a point-in-time snapshot read has expired.

What role do engineers need to check collection stats for this error?

The built-in read role is enough to inspect non-system collections safely. It allows find, collection stats, and database stats actions without letting users modify or drop data.

The query runs. The emails stay hidden.