How to Fix MongoDB Error 464 (ShardRemovedError)
You get mongodb error 464 when a shard leaves a cluster while a change stream runs. To fix this error, open a new change stream without the old resume token. MongoDB names this failure ShardRemovedError and marks it as a NonResumableChangeStreamError. Your app cannot continue from its last saved point after a shard leaves. You must handle this state in your app code to keep data pipelines running. Why mongodb error 464 happens in sharded clusters A change stream watches data updates across y
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 464 when a shard leaves a cluster while a change stream runs. To fix this error, open a new change stream without the old resume token.
MongoDB names this failure ShardRemovedError and marks it as a NonResumableChangeStreamError. Your app cannot continue from its last saved point after a shard leaves. You must handle this state in your app code to keep data pipelines running.
Why mongodb error 464 happens in sharded clusters
A change stream watches data updates across your whole sharded cluster. It merges events from every active shard into one ordered list for your app. When an admin removes a shard, the cluster drains all data chunks from it. Once that shard leaves the cluster, its local change history is gone.
If your change stream tries to read from that removed shard, the database stops it. The server returns code 464, which is ShardRemovedError. Because the error belongs to the NonResumableChangeStreamError group, normal retry logic will fail. If your app sends the old resume token again, the cluster rejects it. The cluster can no longer verify the stream history from the missing shard.
This issue often happens during planned cluster scale-downs or hardware migrations. Teams remove a shard to cut costs, and background workers crash right after. Apps that rely on automatic driver retries will get stuck in an error loop. You must build a recovery path that detects code 464 and resets the stream.
How to diagnose and fix ShardRemovedError safely
First, check your app logs and database logs to confirm the exact error code. Look for code 464 and the ShardRemovedError label in the failed stream output. Next, check with your ops team to see if a shard removal just finished. You do not need broad admin rights on the cluster to fix the app.
MongoDB grants access through roles that allow specific actions on defined resources. A role applies to its target database and works down to the collection level. Your worker app only needs the built-in read role on the target database. The read role grants the changeStream and find actions on non-system collections. It does not allow insert, update, remove, or dropCollection actions.
MongoDB Authentication & Authorization + End-to-End Encryption: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
Never grant write roles or cluster admin roles just to recover a broken stream. Keep your app on the read role while you run the recovery process. To fix the crash, update your error handler to catch NonResumableChangeStreamError events. When code 464 appears, clear the stored resume token from your app state.
Then, start a fresh change stream cursor on the collection or database. If your app cannot miss any updates, run a quick find query first. Use the read role to scan for records updated since your last good timestamp. Once your state catches up, let the new change stream watch for live events. When engineers check production data during this fix, masking rewrites emails and phone numbers.
How to prevent change stream crashes during maintenance
Good planning stops shard changes from breaking your downstream data workers. Before you remove a shard, list every service that runs a change stream. Schedule the final cutover of the shard drain during a low-traffic window.
Test your error handler in a staging cluster before you change production shards. Make sure your code drops the old token as soon as code 464 arrives. Keep your database roles tight so that recovery reads cannot alter live records. Note that self-hosted and Atlas users have different built-in roles from the same actions. Always pick the smallest role that includes the changeStream action for your app.
Add command guardrails and field masking beside MongoDB
Collection roles and IP rules control who connects to MongoDB. Yet an active client or agent session can still run a pipeline that writes data or reads raw personal fields. In practice, hoop.dev sits inline in the wire protocol beside your database as a sidecar for your MongoDB. For every command an agent or human sends in production, hoop.dev decides to pass, mask, block, or escalate it for review.
Using hoop.dev MongoDB controls, guardrails refuse banned commands before they run or hold risky calls for approval, and data masking rewrites matched fields in returned documents in memory. Furthermore, hoop.dev holds SOC 2 Type II, is MIT licensed, and generates evidence for GDPR, HIPAA, and PCI DSS programs. View the project on GitHub.
Frequently asked questions
Can I use a resume token after getting mongodb error 464?
No, ShardRemovedError is a NonResumableChangeStreamError, so old resume tokens will fail. You must discard the old token and open a brand new change stream.
What database role does my app need to restart a change stream?
Your app only needs the built-in read role on the target database. That role includes the changeStream and find actions without granting any write permissions.
Does removing a shard delete data that my change stream missed?
No, MongoDB moves all data chunks to remaining shards before removing the old shard. You can run a standard find query to read any updates your stream missed.
Related guides
In this post