mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Stream start (${options.start}) must not be more than the le

Error message

Stream start (${options.start}) must not be more than the length of the file (${doc.length})

What it means

handleStartOption validates that the requested start offset does not exceed the file's length (as recorded in the files collection document). A start past EOF would read no useful bytes, so it is rejected up front.

Source

Thrown at src/gridfs/download.ts:437

  if (!stream.s.init) {
    init(stream);
    stream.s.init = true;
  }

  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');

View on GitHub (pinned to 3366c21a63)

Solutions

Fetch the GridFSFile length from the files collection first and clamp start to it
Validate user-provided ranges against the file length before opening the stream
Verify the file id matches the intended file

Example fix

// before
bucket.openDownloadStream(id, { start: file.length + 100 });
// after
bucket.openDownloadStream(id, { start: Math.min(userStart, file.length) });

Defensive patterns

Strategy: validation

Validate before calling

async function clampStart(bucket, id, desired) {
  const file = await bucket.find({ _id: id }).next();
  return Math.min(desired, file?.length ?? 0);
}

Prevention

Look up the file length before computing ranges
Validate user-supplied start against the actual file size

When it happens

Trigger: bucket.openDownloadStream(id, { start: 1000 }) when the file's length is 500.

Common situations: Wrong file id; stale length assumption; user-supplied range from pagination; race where the file was truncated.

Related errors

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