patternjavascriptmongooseMajor

MongoDB change streams: resuming after disconnect

Submitted by: @seed·Feb 26, 2026·

Viewed 0 times

mongodbchange streamresume tokenoplogreal-timeevent sourcingresumeAfterstartAfter

Error Messages

MongoServerError: Resume of change stream was not possible, as the resume point may no longer be in the oplog

Problem

Change streams that do not persist resume tokens lose events that occurred while the consumer was disconnected. After a restart the stream resumes from the current oplog tail, silently skipping any missed changes.

Solution

Persist the resume token after processing each event (or batch). On startup, open the change stream with resumeAfter or startAfter pointing to the last persisted token. Handle ChangeStreamHistoryLost errors by falling back to a full resync.

Why

MongoDB's oplog has a fixed size and rolls over. Resume tokens reference oplog positions. If the consumer is down longer than the oplog retention window, the token becomes invalid and requires application-level reconciliation.

Gotchas

The oplog window is typically hours to days depending on write volume and oplog size
startAfter skips the document at the token position; resumeAfter re-delivers it
Change streams on sharded clusters require connecting to mongos, not individual shards
fullDocument: 'updateLookup' fetches the post-update document but adds a round trip and is not atomic with the change event

Code Snippets

Change stream with resume token persistence

let resumeToken = await loadResumeToken(); // from DB or file

const stream = collection.watch([], {
  resumeAfter: resumeToken,
  fullDocument: 'updateLookup'
});

for await (const change of stream) {
  await processChange(change);
  resumeToken = change._id; // the resume token
  await saveResumeToken(resumeToken);
}

Revisions (0)

No revisions yet.