mongodb/node-mongodb-native · error · MongoInvalidArgumentError

End option must be defined

Error message

End option must be defined

What it means

Defensive internal error in handleEndOption reached when the function is invoked without a defined options.end. The public API always defaults end to 0, so reaching this typically indicates direct manipulation of stream private state or a driver regression.

Source

Thrown at src/gridfs/download.ts:482

  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`);
    }

    const start = options.start != null ? Math.floor(options.start / doc.chunkSize) : 0;

    cursor.limit(Math.ceil(options.end / doc.chunkSize) - start);

    stream.s.expectedEnd = Math.ceil(options.end / doc.chunkSize);

    return Math.ceil(options.end / doc.chunkSize) * doc.chunkSize - options.end;
  }
  throw new MongoInvalidArgumentError('End option must be defined');
}

View on GitHub (pinned to 3366c21a63)

Solutions

  1. Use only the public openDownloadStream API
  2. Never assign stream.s.options.end = null/undefined manually
  3. If reproduced on the latest driver, file a bug
Defensive patterns

Strategy: try-catch

Try / catch

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

Prevention

When it happens

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

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

Related errors

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