mongodb/node-mongodb-native · error · MongoInvalidArgumentError

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

Error message

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

What it means

handleStartOption rejects negative start offsets because byte offsets are 0-indexed and non-negative. This guards against off-by-one pagination math and unvalidated user input.

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 3366c21a63)

Solutions

  1. Clamp start with Math.max(0, n) before opening the stream
  2. Validate user-provided offsets are non-negative integers

Example fix

// before
{ start: offset - 1 } // offset 0 yields -1
// after
{ start: Math.max(0, offset - 1) }
Defensive patterns

Strategy: validation

Validate before calling

const safeStart = Math.max(0, Number(userStart) || 0);

Type guard

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

Prevention

When it happens

Trigger: bucket.openDownloadStream(id, { start: -1 }) or any path producing a negative start.

Common situations: Pagination math like offset - 1 with offset 0; unvalidated query params; swapped subtraction order.

Related errors

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