{"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/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/gridfs/download.ts#L437-L473","documentation":"Defensive internal error in handleStartOption reached when the function is invoked without a defined options.start. The public path (openDownloadStream options) always supplies one, so seeing this error usually means direct manipulation of stream private state or a driver regression.","triggerScenarios":"Internal invocation of handleStartOption with options.start == null, or manual mutation of stream.s.options.start to null/undefined.","commonSituations":"Driver bug; tampering with stream.s.options directly; a fork that altered the init flow.","solutions":["Use only the public openDownloadStream API to set byte ranges","Never assign stream.s.options.start = null/undefined directly","If reproduced on the latest driver, file a bug with the call sequence"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  for await (const chunk of stream) { /* ... */ }\n} catch (err) {\n  if (err instanceof MongoInvalidArgumentError && /Start option must be defined/i.test(err.message)) {\n    // unexpected internal path; report and recreate the stream\n  } else throw err;\n}","preventionTips":["Use only public GridFS APIs to configure byte ranges","Do not mutate stream.s.options directly"],"tags":["gridfs","stream","internal"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}