mongodb/node-mongodb-native · error · MongoGridFSStreamError

Options cannot be changed after the stream is initialized

Error message

Options cannot be changed after the stream is initialized

What it means

GridFSBucketReadStream.start()/end() set byte-range options but only before the stream has initialized (fetched the file document). Once init is true (after the first _read or a 'file' event), the range math is fixed and late mutations are rejected to avoid corrupting bytesToSkip/bytesToTrim.

Source

Thrown at src/gridfs/download.ts:213

    return this;
  }

  /**
   * Marks this stream as aborted (will never push another `data` event)
   * and kills the underlying cursor. Will emit the 'end' event, and then
   * the 'close' event once the cursor is successfully killed.
   */
  async abort(): Promise<void> {
    this.push(null);
    this.destroy();
    const remainingTimeMS = this.s.timeoutContext?.getRemainingTimeMSOrThrow();
    await this.s.cursor?.close({ timeoutMS: remainingTimeMS });
  }
}

function throwIfInitialized(stream: GridFSBucketReadStream): void {
  if (stream.s.init) {
    throw new MongoGridFSStreamError('Options cannot be changed after the stream is initialized');
  }
}

function doRead(stream: GridFSBucketReadStream): void {
  if (stream.destroyed) return;
  if (!stream.s.cursor) return;
  if (!stream.s.file) return;

  const handleReadResult = (doc: Document | null) => {
    if (stream.destroyed) return;

    if (!doc) {
      stream.push(null);

      stream.s.cursor?.close().then(undefined, error => stream.destroy(error));
      return;
    }

View on GitHub (pinned to 3366c21a63)

Solutions

1. Pass start/end in the openDownloadStream options at construction time
2. Call .start()/.end() before attaching any 'data' listener or calling read()
3. Open a brand-new stream if the range needs to change mid-flight

Example fix

// before
const s = bucket.openDownloadStream(id);
s.on('data', cb);
s.start(100); // throws
// after
const s = bucket.openDownloadStream(id, { start: 100 });
s.on('data', cb);

function openRange(bucket, id, start, end) {
  // always configure range at construction
  return bucket.openDownloadStream(id, { start, end });
}

When it happens

Trigger: Calling .start(100) or .end(500) after attaching a 'data' listener, calling .read(), or emitting the 'file' event.

Common situations: Lazy range configuration inside event handlers; reusing a stream after partial consumption; chaining .start() after pipe().

Related errors

• Stream start (${options.start}) must not be more than the le
• Stream start (${options.start}) must not be negative
• Stream start (${options.start}) must not be greater than str
• Start option must be defined
• Stream end (${options.end}) must not be more than the length

AI-assisted analysis of mongodb/node-mongodb-native@3366c21a63 (2026-08-04). Data as JSON: /data/errors/7c675547c72b1a82.json. Report an issue: GitHub.