How to Fix MongoDB Error 286 (ChangeStreamHistoryLost)

Published
Length
3 min read

Luis Felipe Dias

All posts

You get mongodb error 286 when a change stream tries to resume from a dropped oplog entry. You fix it by starting a fresh change stream and increasing your oplog retention window. MongoDB names this failure ChangeStreamHistoryLost and marks it as a NonResumableChangeStreamError. Your app waited too long to reconnect, and the database rolled over old write history. Because the resume token points to missing history, the stream cannot continue from that point. What causes mongodb error 286 in p

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 286 when a change stream tries to resume from a dropped oplog entry. You fix it by starting a fresh change stream and increasing your oplog retention window.

MongoDB names this failure ChangeStreamHistoryLost and marks it as a NonResumableChangeStreamError. Your app waited too long to reconnect, and the database rolled over old write history. Because the resume token points to missing history, the stream cannot continue from that point.

What causes mongodb error 286 in production clusters

Change streams watch the replica set oplog to track data edits in real time. Each event holds a resume token that marks its exact place in the oplog. If a network drop stops your worker, the app saves that last resume token. When the worker comes back online, it sends the token to resume reading events.

The oplog has a fixed size or time limit on disk. New writes push out the oldest entries once the log reaches its limit. If your app stays down longer than the oplog window, those old entries vanish. When the client asks for the old token, the server returns error code 286.

Heavy batch jobs often cause this problem during peak hours. A huge bulk update writes millions of records to the oplog in minutes. This spike shrinks the time window that your oplog can hold on disk. Even a short worker pause during a write spike can trigger ChangeStreamHistoryLost.

How to diagnose and fix the failure safely

To recover right away, your app must catch this non-resumable error and start over. Clear the expired resume token from your local state store. Open a new change stream cursor without passing the old token. Next, run a background read to sync any records missed during the outage.

Engineers often need to check cluster stats to see why the oplog rolled over. Do not grant full admin rights just to inspect database metrics or test streams. MongoDB grants access through role-based rules that apply down to the collection level. The built-in read role grants actions like find, listCollections, listIndexes, dbStats, collStats, and changeStream.

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

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Assigning the read role lets engineers check collection stats and test change streams safely. This role excludes write actions like insert, update, remove, or dropCollection. If your team reads live records during recovery, apply data masking to the query stream. Masking rewrites matched fields like emails, phone numbers, card numbers, and national IDs in results.

How to prevent change stream history loss

After your worker recovers, you must stop the error from happening again. First, check how many hours of write history your oplog holds during peak load. Size your oplog so it holds more hours than your longest weekend maintenance window. Many teams set a minimum oplog retention time so write spikes do not delete history early.

Second, keep your change stream workers running even when downstream targets slow down. Separate the thread that reads the stream from the thread that processes records. Have your reader save the latest resume token to disk on a steady schedule. Even if a stream sits idle, saving fresh tokens keeps its place near the oplog head.

Third, break huge batch updates into smaller chunks spaced out over time. Small write batches keep the oplog growth rate steady and predictable. Set up alerts when your oplog time window drops below a safe threshold. Early warnings let your team add disk space before any stream loses its history.

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 a change stream auto-resume after error 286?

No, MongoDB classifies error 286 as a NonResumableChangeStreamError. Your app must discard the old resume token, open a new stream, and sync missed records.

Which MongoDB role lets me test change streams safely?

The built-in read role includes the changeStream, dbStats, and collStats actions on non-system collections. It lets you inspect state and test streams without granting insert, update, or remove rights.

Why did error 286 happen after a five-minute outage?

A large batch write can fill the oplog in minutes and push out older entries. Size your oplog for peak write volume so short outages never lose stream history.

The query runs. The emails stay hidden.