How to Fix MongoDB Error 150 (StaleEpoch)

Published
Length
3 min read

Luis Felipe Dias

All posts

You see mongodb error 150 when a query uses an old collection epoch. To fix it, refresh your router metadata and retry the failed request. In the official database rules, code 150 has the name StaleEpoch. It falls under the StaleShardVersionError and NeedRetargettingError categories. This failure happens in sharded clusters when collection metadata changes during a run. A user or app might drop, recreate, or reshard a collection. Routers and shards that hold the old epoch ID reject the call. Th

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 150 when a query uses an old collection epoch. To fix it, refresh your router metadata and retry the failed request.

In the official database rules, code 150 has the name StaleEpoch. It falls under the StaleShardVersionError and NeedRetargettingError categories. This failure happens in sharded clusters when collection metadata changes during a run. A user or app might drop, recreate, or reshard a collection. Routers and shards that hold the old epoch ID reject the call. The system blocks the action so you do not read or write wrong data.

What causes mongodb error 150 in sharded clusters

Sharded clusters split data across many database nodes. Each sharded collection gets a unique epoch marker when you create it. Query routers cache this marker to send requests to the right shard. When a collection drops or moves, the cluster makes a new epoch marker.

If a router still holds the old marker, the shard returns StaleEpoch. The NeedRetargettingError category tells the router to fetch fresh cluster metadata. The StaleShardVersionError category marks the routing cache as out of date. Most drivers and routers catch this code and retry on their own.

You will see the error in your app if retries fail. This happens when scripts drop and recreate collections during heavy read traffic. It also happens when long cursors keeps the session active across a collection change. Network lag between config servers and routers can also delay metadata updates.

How to diagnose and fix StaleEpoch safely in production

Start by checking your cluster logs to find which collection changed. Look for recent drop, rename, or reshard events on that database. You do not need full admin rights to check basic collection stats.

MongoDB grants access through roles on a specific database down to a collection level. The built-in read role lets you run stats and list collections safely. It does not allow insert, update, remove, or drop actions on your data. Use this read role during checks so you do not risk accidental changes.

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

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Once you find the affected collection, check how your app runs schema changes. Stop background tasks from dropping active collections while user traffic is running. If a router keeps failing, ask a cluster admin to flush its metadata cache. Make sure your client driver uses retry logic for retargeting errors.

Preventing stale epoch failures during schema changes

Many teams trigger StaleEpoch by giving too many users broad write access. The readWrite role lets users create and drop collections or indexes. When an engineer or script drops a sharded collection, every open cursor breaks.

Limit the readWrite role to approved deploy pipelines and migration jobs. Give developers the read role for daily checks on production databases. Schedule collection drops and resharding tasks during low traffic windows. Close long running cursors before you change collection structure.

If your team queries live data containing emails or phone numbers, add data masking. Masking rewrites matched fields in query results to protect sensitive values during checks. Combining scoped roles with safe maintenance windows keeps your sharded cluster stable.

Check MongoDB commands and documents on the wire

MongoDB roles and SCRAM login decide who opens a session. They do not check single commands or redact sensitive fields inside returned documents. With hoop.dev, you run an open-source proxy, a sidecar for your MongoDB, inline in the MongoDB wire protocol. On every command an AI agent or engineer runs against production, hoop.dev decides to pass, mask, block, or hold it for human review.

Before a command runs, hoop.dev guardrails check its effect and refuse banned drops or writes with MongoDB error code 13, or hold risky commands for approval. On the way back, hoop.dev data masking rewrites sensitive fields in returned documents in memory, and every verdict is logged. See the open-source code on GitHub.

Frequently asked questions

What does StaleEpoch mean in MongoDB?

StaleEpoch is the official name for error code 150 in a sharded cluster. It means a collection was dropped, recreated, or moved since the router cached it.

Does error 150 mean my shard data is corrupt?

No, this error protects your data from going to the wrong shard. The shard rejects the request because the router has an old metadata version.

How do I stop scripts from causing mongodb error 150?

Remove the readWrite role from accounts that do not need to drop collections. Run collection changes in planned windows and let drivers retry failed calls.

The query runs. The emails stay hidden.