mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Stream end ( ) must not be more than the length of the file…

Error message

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

What it means

handleEndOption (src/gridfs/download.ts:465) validates that the end offset does not exceed the file's actual length (doc.length). If end is greater than the stored size, it throws MongoInvalidArgumentError during stream initialization.

Solutions

  1. Fetch the file metadata (bucket.find({ _id: id })) and confirm end <= file.length before opening the stream.
  2. Clamp end to the file length: Math.min(end, file.length).

Example fix

// before
const s = bucket.openDownloadStream(id, { end: 500000 });
// after
const file = await bucket.find({ _id: id }).next();
const s = bucket.openDownloadStream(id, { end: Math.min(500000, file.length) });
Defensive patterns

Strategy: validation

Validate before calling

async function safeOpenEnd(bucket, id, end) {
  const file = await bucket.find({ _id: id }).next();
  if (!file) throw new Error('file not found');
  if (end > file.length) end = file.length;
  return bucket.openDownloadStream(id, { start: 0, end });
}

Type guard

function isEndWithinLength(end: number, length: number): boolean {
  return Number.isInteger(end) && end >= 0 && end <= length;
}

Try / catch

try {
  bucket.openDownloadStream(id, { start: 0, end });
} catch (e) {
  if (e instanceof MongoInvalidArgumentError && /must not be more than the length/.test(e.message)) {
    // clamp end to length
  }
}

Prevention

When it happens

Trigger: Calling openDownloadStream(id, { end: N }) where N > file length. Passing a hardcoded end offset that is valid for some files but not for a shorter one.

Common situations: Assuming a file is larger than it is (e.g. reading with end from a stale content-length header). Using the same range for files of differing sizes.

Related errors

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

Appendix: source

Thrown at src/gridfs/download.ts:466

    }

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

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