mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Start option must be defined

Error message

Start option must be defined

What it means

Defensive internal error in handleStartOption reached when the function is invoked without a defined options.start. The public path (openDownloadStream options) always supplies one, so seeing this error usually means direct manipulation of stream private state or a driver regression.

Source

Thrown at src/gridfs/download.ts:455

      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
) {
  if (options && options.end != null) {
    if (options.end > doc.length) {
      throw new MongoInvalidArgumentError(
        `Stream end (${options.end}) must not be more than the length of the file (${doc.length})`
      );
    }
    if (options.start == null || options.start < 0) {
      throw new MongoInvalidArgumentError(`Stream end (${options.end}) must not be negative`);
    }

View on GitHub (pinned to 3366c21a63)

Solutions

1. Use only the public openDownloadStream API to set byte ranges
2. Never assign stream.s.options.start = null/undefined directly
3. If reproduced on the latest driver, file a bug with the call sequence

try {
  for await (const chunk of stream) { /* ... */ }
} catch (err) {
  if (err instanceof MongoInvalidArgumentError && /Start option must be defined/i.test(err.message)) {
    // unexpected internal path; report and recreate the stream
  } else throw err;
}

When it happens

Trigger: Internal invocation of handleStartOption with options.start == null, or manual mutation of stream.s.options.start to null/undefined.

Common situations: Driver bug; tampering with stream.s.options directly; a fork that altered the init flow.

Related errors

• End option must be defined
• Options cannot be changed after the stream is initialized
• 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

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