mongodb/node-mongodb-native · error · MongoChangeStreamError

Parent provided to ChangeStream constructor must be an…

Error message

Parent provided to ChangeStream constructor must be an instance of Collection, Db, or MongoClient

What it means

Thrown by the ChangeStream constructor when the parent argument is not an instance of Collection, Db, or MongoClient. The driver uses the parent type to determine the change stream's domain (collection-level, database-level, or cluster-level) and to access the underlying MongoClient. This is a MongoChangeStreamError.

Solutions

Do not construct ChangeStream directly; use collection.watch(), db.watch(), or client.watch() instead
If you must construct directly, ensure the parent is a genuine Collection, Db, or MongoClient instance (not a wrapper or mock)
Check parent instanceof Collection || parent instanceof Db || parent instanceof MongoClient before construction

Example fix

// before
const stream = new ChangeStream(someTopologyObject, pipeline);

// after
const stream = collection.watch(pipeline);
// or: db.watch(pipeline)
// or: client.watch(pipeline)

Defensive patterns

Strategy: validation

Validate before calling

// Before constructing a ChangeStream directly
import { Collection, Db, MongoClient } from 'mongodb';
if (!(parent instanceof Collection || parent instanceof Db || parent instanceof MongoClient)) {
  throw new TypeError('parent must be Collection, Db, or MongoClient');
}

Type guard

import type { Collection, Db, MongoClient } from 'mongodb';
function isValidChangeStreamParent(parent: unknown): parent is Collection | Db | MongoClient {
  return parent instanceof Collection || parent instanceof Db || parent instanceof MongoClient;
}

Prevention

Never construct ChangeStream directly; always use collection.watch(), db.watch(), or client.watch()
If wrapping the driver, validate the parent type before passing it to ChangeStream

When it happens

Trigger: Directly instantiating new ChangeStream(parent, pipeline, options) where parent is something other than a Collection, Db, or MongoClient instance (e.g., a raw topology, a cursor, or null). The normal entry points (collection.watch(), db.watch(), client.watch()) always pass a valid parent, so this only occurs with direct construction.

Common situations: Subclassing or wrapping ChangeStream and passing a mock or proxy object; copying example code that manually constructs a ChangeStream; library or framework code that abstracts over the driver and passes the wrong object type.

Related errors

AI-assisted analysis of mongodb/node-mongodb-native@dce7939f86 (2026-08-11). Data as JSON: /api/errors/a503f39a368cb067. Report an issue: GitHub.

Appendix: source

Thrown at src/change_stream.ts:663

  ) {
    super();

    this.pipeline = pipeline;
    this.options = { ...options };
    let serverSelectionTimeoutMS: number;
    delete this.options.writeConcern;

    if (parent instanceof Collection) {
      this.type = CHANGE_DOMAIN_TYPES.COLLECTION;
      serverSelectionTimeoutMS = parent.s.db.client.options.serverSelectionTimeoutMS;
    } else if (parent instanceof Db) {
      this.type = CHANGE_DOMAIN_TYPES.DATABASE;
      serverSelectionTimeoutMS = parent.client.options.serverSelectionTimeoutMS;
    } else if (parent instanceof MongoClient) {
      this.type = CHANGE_DOMAIN_TYPES.CLUSTER;
      serverSelectionTimeoutMS = parent.options.serverSelectionTimeoutMS;
    } else {
      throw new MongoChangeStreamError(
        'Parent provided to ChangeStream constructor must be an instance of Collection, Db, or MongoClient'
      );
    }

    this.contextOwner = Symbol();
    this.parent = parent;
    this.namespace = parent.s.namespace;
    if (!this.options.readPreference && parent.readPreference) {
      this.options.readPreference = parent.readPreference;
    }

    // Create contained Change Stream cursor
    this.cursor = this._createChangeStreamCursor(options);

    this.isClosed = false;
    this.mode = false;

    // Listen for any `change` listeners being added to ChangeStream

View on GitHub (pinned to dce7939f86)