What causes "Stream start (${options.start}) must not be negative" in mongodb/node-mongodb-native?

Ensure start is a non-negative integer; clamp with Math.max(0, value).

mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Stream start ( ) must not be negative

Error message

Stream start (${options.start}) must not be negative

What it means

handleStartOption (src/gridfs/download.ts:441) rejects negative start offsets with MongoInvalidArgumentError. The start parameter is a 0-based byte offset, so negative values are meaningless and indicate a caller bug.

Solutions

Ensure start is a non-negative integer; clamp with Math.max(0, value).
Validate the input at the application boundary and reject/normalize negative offsets before calling openDownloadStream.

Example fix

// before
const s = bucket.openDownloadStream(id, { start: offset - 50 });
// after
const s = bucket.openDownloadStream(id, { start: Math.max(0, offset - 50) });

Defensive patterns

Strategy: validation

Validate before calling

function clampStart(start) {
  return Math.max(0, Math.floor(start));
}
const s = bucket.openDownloadStream(id, { start: clampStart(userStart) });

Type guard

function isNonNegativeInt(v: unknown): v is number {
  return typeof v === 'number' && Number.isInteger(v) && v >= 0;
}

Try / catch

try {
  bucket.openDownloadStream(id, { start });
} catch (e) {
  if (e instanceof MongoInvalidArgumentError && /must not be negative/.test(e.message)) {
    start = 0;
  }
}

Prevention

Clamp offset arithmetic with Math.max(0, value).
Validate range inputs at the API boundary.
Add tests around offset edge cases (zero, below zero).

When it happens

Trigger: Calling openDownloadStream(id, { start: -1 }) or stream.start(-10). Passing a computed offset that underflows to a negative number (e.g. subtracting too aggressively).

Common situations: Arithmetic on offsets producing negatives when the file is smaller than a chunk size assumption. Off-by-one errors in resume logic.

Related errors

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

Appendix: source

Thrown at src/gridfs/download.ts:442

  stream.once('file', () => {
    callback();
  });
}

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,

View on GitHub (pinned to dce7939f86)