{"record":{"id":"a59602f6b8bef9f6","repo":"mongodb/node-mongodb-native","slug":"start-option-must-be-defined","errorCode":null,"errorMessage":"Start option must be defined","messagePattern":"Start option must be defined","errorType":"exception","errorClass":"MongoInvalidArgumentError","httpStatus":null,"severity":"error","filePath":"src/gridfs/download.ts","lineNumber":455,"sourceCode":"      throw new MongoInvalidArgumentError(\n        `Stream start (${options.start}) must not be more than the length of the file (${doc.length})`\n      );\n    }\n    if (options.start < 0) {\n      throw new MongoInvalidArgumentError(`Stream start (${options.start}) must not be negative`);\n    }\n    if (options.end != null && options.end < options.start) {\n      throw new MongoInvalidArgumentError(\n        `Stream start (${options.start}) must not be greater than stream end (${options.end})`\n      );\n    }\n\n    stream.s.bytesRead = Math.floor(options.start / doc.chunkSize) * doc.chunkSize;\n    stream.s.expected = Math.floor(options.start / doc.chunkSize);\n\n    return options.start - stream.s.bytesRead;\n  }\n  throw new MongoInvalidArgumentError('Start option must be defined');\n}\n\nfunction handleEndOption(\n  stream: GridFSBucketReadStream,\n  doc: Document,\n  cursor: FindCursor<GridFSChunk>,\n  options: GridFSBucketReadStreamOptions\n) {\n  if (options && options.end != null) {\n    if (options.end > doc.length) {\n      throw new MongoInvalidArgumentError(\n        `Stream end (${options.end}) must not be more than the length of the file (${doc.length})`\n      );\n    }\n    if (options.start == null || options.start < 0) {\n      throw new MongoInvalidArgumentError(`Stream end (${options.end}) must not be negative`);\n    }\n","sourceCodeStart":437,"sourceCodeEnd":473,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/gridfs/download.ts#L437-L473","documentation":"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.","triggerScenarios":"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.","commonSituations":"Rare for end users; typically only seen when monkeypatching or subclassing GridFSBucketReadStream. Most user-facing cases are covered by the explicit start validations above.","solutions":["Do not subclass or mutate GridFSBucketReadStream internals; provide start via openDownloadStream(id, { start }).","If reached through a public path, ensure the options object passed to the stream always includes start when range reading is intended."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Internal guard. Avoid subclassing GridFSBucketReadStream.\n// Always provide start via openDownloadStream options.\nfunction openSafe(bucket, id, range) {\n  if (range?.start == null) delete range?.start;\n  return bucket.openDownloadStream(id, range && range.start != null ? range : undefined);\n}","typeGuard":"function hasStart(range: unknown): range is { start: number } {\n  return range != null && typeof (range as any).start === 'number';\n}","tryCatchPattern":null,"preventionTips":["Do not subclass or mutate GridFSBucketReadStream internals.","Provide start via the openDownloadStream options object.","Report a bug if this surfaces through a normal public API path."],"tags":["gridfs","stream","internal","validation"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}