mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Stream start ( ) must not be greater than stream end ( )

Q: What causes "Stream start (${options.start}) must not be greater than stream end (${options.end})" in mongodb/node-mongodb-native?

Ensure start <= end; swap or clamp values before opening the stream.

Error message

Stream start (${options.start}) must not be greater than stream end (${options.end})

What it means

handleStartOption (src/gridfs/download.ts:444) checks that start does not exceed end. If both are provided and end < start, it throws MongoInvalidArgumentError because the byte range would be inverted/empty.

Solutions

Ensure start <= end; swap or clamp values before opening the stream.
Validate range inputs (start <= end) at the application boundary.

Example fix

// before
const s = bucket.openDownloadStream(id, { start: 100, end: 50 });
// after
const s = bucket.openDownloadStream(id, { start: Math.min(a, b), end: Math.max(a, b) });

Defensive patterns

Strategy: validation

Validate before calling

function normalizeRange(start, end) {
  if (start != null && end != null && end < start) [start, end] = [end, start];
  return { start, end };
}

Type guard

function isOrderedRange(start: number, end: number): boolean {
  return start <= end;
}

Try / catch

try {
  bucket.openDownloadStream(id, { start, end });
} catch (e) {
  if (e instanceof MongoInvalidArgumentError && /greater than stream end/.test(e.message)) {
    [start, end] = [end, start];
  }
}

Prevention

Always order range bounds (min/max) before passing to the stream.
Validate start <= end at the request boundary.
Use named parameters/object destructuring to avoid swapping start and end.

When it happens

Trigger: Calling openDownloadStream(id, { start: 100, end: 50 }) or stream.start(100).end(50). Passing swapped start/end arguments.

Common situations: Variable assignment where start and end are filled from a request in the wrong order. Resume logic that computes end before start and gets the comparison backwards.

Related errors

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

Appendix: source

Thrown at src/gridfs/download.ts:445

  });
}

function handleStartOption(
  stream: GridFSBucketReadStream,
  doc: Document,
  options: GridFSBucketReadStreamOptions
): number {
  if (options && options.start != null) {
    if (options.start > doc.length) {
      throw new MongoInvalidArgumentError(
        `Stream start (${options.start}) must not be more than the length of the file (${doc.length})`
      );
    }
    if (options.start < 0) {
      throw new MongoInvalidArgumentError(`Stream start (${options.start}) must not be negative`);
    }
    if (options.end != null && options.end < options.start) {
      throw new MongoInvalidArgumentError(
        `Stream start (${options.start}) must not be greater than stream end (${options.end})`
      );
    }

    stream.s.bytesRead = Math.floor(options.start / doc.chunkSize) * doc.chunkSize;
    stream.s.expected = Math.floor(options.start / doc.chunkSize);

    return options.start - stream.s.bytesRead;
  }
  throw new MongoInvalidArgumentError('Start option must be defined');
}

function handleEndOption(
  stream: GridFSBucketReadStream,
  doc: Document,
  cursor: FindCursor<GridFSChunk>,
  options: GridFSBucketReadStreamOptions
) {

View on GitHub (pinned to dce7939f86)