mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Start option must be defined

Error message

Start option must be defined

What it means

handleStartOption (src/gridfs/download.ts:455) is an internal function reached when start is expected but options.start is null/undefined. Throwing 'Start option must be defined' indicates an internal call-path reached the helper without a start value; users normally hit the sibling validations (266/267/268) instead. It surfaces as a defensive MongoInvalidArgumentError guard inside the stream initialization.

Solutions

  1. Do not subclass or mutate GridFSBucketReadStream internals; provide start via openDownloadStream(id, { start }).
  2. If reached through a public path, ensure the options object passed to the stream always includes start when range reading is intended.
Defensive patterns

Strategy: validation

Validate before calling

// Internal guard. Avoid subclassing GridFSBucketReadStream.
// Always provide start via openDownloadStream options.
function openSafe(bucket, id, range) {
  if (range?.start == null) delete range?.start;
  return bucket.openDownloadStream(id, range && range.start != null ? range : undefined);
}

Type guard

function hasStart(range: unknown): range is { start: number } {
  return range != null && typeof (range as any).start === 'number';
}

Prevention

When it happens

Trigger: An internal or custom subclass invoking handleStartOption without a start value. Edge cases where the stream options object is mutated to remove start between construction and initialization.

Common situations: Rare for end users; typically only seen when monkeypatching or subclassing GridFSBucketReadStream. Most user-facing cases are covered by the explicit start validations above.

Related errors

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

Appendix: 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 dce7939f86)