How to Fix MongoDB Error 280 (ChangeStreamFatalError)

Published
Length
3 min read

Luis Felipe Dias

All posts

You get mongodb error 280 when a change stream hits an unrecoverable failure. To fix it, restart the stream with a fresh cursor and valid permissions. MongoDB names this failure ChangeStreamFatalError and puts it in the NonResumableChangeStreamError category. When this code appears, the database closes your open change stream cursor right away. Your app cannot resume from the old token after a non-resumable error occurs. You must inspect the root cause before opening a new stream on the databas

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 280 when a change stream hits an unrecoverable failure. To fix it, restart the stream with a fresh cursor and valid permissions.

MongoDB names this failure ChangeStreamFatalError and puts it in the NonResumableChangeStreamError category. When this code appears, the database closes your open change stream cursor right away. Your app cannot resume from the old token after a non-resumable error occurs. You must inspect the root cause before opening a new stream on the database.

What causes mongodb error 280 in your cluster

A change stream watches a collection or database for real-time data changes. It relies on the oplog and strict user permissions to run without stopping. When an event breaks the stream state beyond repair, MongoDB throws code 280. Because it is a NonResumableChangeStreamError, a simple driver retry will not work.

Missing or revoked user permissions often trigger this fatal change stream failure. MongoDB controls database actions through role-based access rules on specific resources. A role applies to its home database and works down to the collection level. If an admin revokes the changeStream action mid-flight, the cursor fails with code 280.

Pipeline stage errors or dropped collections can also trigger a ChangeStreamFatalError in production. If the watched collection changes in an unsupported way, the stream stops. Oplog rollovers also break streams when a cursor falls too far behind recent writes. Once the needed oplog history is gone, the database marks the error as non-resumable.

How to diagnose and fix ChangeStreamFatalError safely

Start by checking your server logs and app logs around the failure timestamp. Look for the exact text paired with the ChangeStreamFatalError message in your logs. The log detail tells you if permissions, oplog size, or pipeline rules failed. Never fix this issue by granting broad admin roles to your app user.

Check the database roles assigned to the user account running the change stream. The built-in read role grants read access to all non-system collections in its database. This read role includes find, listCollections, listIndexes, dbStats, collStats, and changeStream actions. It leaves out write actions like insert, update, remove, or dropCollection for safety.

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

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

If your app only watches data, assign the read role on that database. If the app also modifies data, the readWrite role adds write actions safely. Note that MongoDB Atlas users have different built-in roles than self-hosted deployment users. Still, both setups build their roles from the very same privilege actions.

After you confirm the user role has the changeStream action, check your app logic. Your code must catch NonResumableChangeStreamError events and discard the broken resume token. Have the app start a brand new change stream cursor from the current time. Run a quick read check to sync any missed records during the brief outage.

How to prevent future change stream failures

You can stop most fatal stream errors with better role hygiene and monitoring. Keep human engineers from changing collection rules or roles during peak traffic hours. When people run ad-hoc commands in production, they often break active app streams. Restrict direct database sessions and require peer review for any schema or role change.

Watch your oplog window size so slow consumers never fall off the end. Alert your team when replication lag grows or when fatal error codes spike. Also, use data masking on read queries to rewrite emails and card numbers. This protects sensitive fields in results while engineers inspect broken stream payloads.

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 ChangeStreamFatalError mean in MongoDB?

ChangeStreamFatalError is the official name for error code 280 in MongoDB. It belongs to the NonResumableChangeStreamError category, meaning the cursor cannot resume from its token.

Which MongoDB role is needed to run a change stream?

The built-in read role includes the changeStream action on non-system collections in its database. You do not need to grant readWrite or admin roles just to watch changes.

Can my app auto-resume after hitting mongodb error 280?

No, you cannot resume with the old token because the error is non-resumable. Your app must drop the old token, open a new stream, and re-sync state.

The query runs. The emails stay hidden.