{"id":"035b532f1201a792","repo":"mongodb/node-mongodb-native","slug":"unrecognized-options","errorCode":null,"errorMessage":"Unrecognized options","messagePattern":"Unrecognized options","errorType":"exception","errorClass":"MongoRuntimeError","httpStatus":null,"severity":"error","filePath":"src/timeout.ts","lineNumber":170,"sourceCode":"\nfunction isCSOTTimeoutContextOptions(v: unknown): v is CSOTTimeoutContextOptions {\n  return (\n    v != null &&\n    typeof v === 'object' &&\n    'serverSelectionTimeoutMS' in v &&\n    typeof v.serverSelectionTimeoutMS === 'number' &&\n    'timeoutMS' in v &&\n    typeof v.timeoutMS === 'number'\n  );\n}\n\n/** @internal */\nexport abstract class TimeoutContext {\n  static create(options: TimeoutContextOptions): TimeoutContext {\n    if (options.session?.timeoutContext != null) return options.session?.timeoutContext;\n    if (isCSOTTimeoutContextOptions(options)) return new CSOTTimeoutContext(options);\n    else if (isLegacyTimeoutContextOptions(options)) return new LegacyTimeoutContext(options);\n    else throw new MongoRuntimeError('Unrecognized options');\n  }\n\n  abstract get maxTimeMS(): number | null;\n\n  abstract get serverSelectionTimeout(): Timeout | null;\n\n  abstract get connectionCheckoutTimeout(): Timeout | null;\n\n  abstract get clearServerSelectionTimeout(): boolean;\n\n  abstract get timeoutForSocketWrite(): Timeout | null;\n\n  abstract get timeoutForSocketRead(): Timeout | null;\n\n  abstract csotEnabled(): this is CSOTTimeoutContext;\n\n  abstract refresh(): void;\n","sourceCodeStart":152,"sourceCodeEnd":188,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/timeout.ts#L152-L188","documentation":"Thrown by the @internal TimeoutContext.create() factory when the options object matches neither the CSOT shape ({ timeoutMS, serverSelectionTimeoutMS }) nor the Legacy shape ({ serverSelectionTimeoutMS, waitQueueTimeoutMS }). This indicates the factory was called with a malformed options bag. It is a MongoRuntimeError.","triggerScenarios":"Driver-internal code constructing a TimeoutContext with missing or mis-typed fields (e.g. serverSelectionTimeoutMS omitted, or waitQueueTimeoutMS absent in legacy mode). Not reachable through the public API directly.","commonSituations":"Driver bugs in timeout-context wiring; tests/mocks that build options bags by hand without all required keys; regressions after refactoring timeout option propagation.","solutions":["Ensure the options bag passed to TimeoutContext.create contains all required keys for either the CSOT or Legacy shape.","Upgrade the driver - this path is internal and the cause is almost always a driver bug; report it with the operation and options used.","If writing driver tests, use the helpers that construct TimeoutContextOptions rather than hand-building the object."],"exampleFix":"// before (internal)\nTimeoutContext.create({ serverSelectionTimeoutMS: 30000 }); // throws: missing waitQueueTimeoutMS / timeoutMS\n\n// after\nTimeoutContext.create({ serverSelectionTimeoutMS: 30000, waitQueueTimeoutMS: 120000 }); // legacy\n// or\nTimeoutContext.create({ timeoutMS: 10000, serverSelectionTimeoutMS: 30000 }); // CSOT","handlingStrategy":"validation","validationCode":"// internal: ensure required keys before creating a context\nfunction isCSOT(o: any) {\n  return typeof o?.timeoutMS === 'number' && typeof o?.serverSelectionTimeoutMS === 'number';\n}\nfunction isLegacy(o: any) {\n  return typeof o?.serverSelectionTimeoutMS === 'number' && typeof o?.waitQueueTimeoutMS === 'number';\n}\nif (isCSOT(opts) || isLegacy(opts)) {\n  TimeoutContext.create(opts);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["In driver internals/tests, always build TimeoutContextOptions via the documented helpers, not by hand.","Upgrade the driver if you see this - it almost always indicates an internal bug.","Add type checks on both serverSelectionTimeoutMS and (timeoutMS | waitQueueTimeoutMS) before calling create()."],"tags":["timeout","csot","internal","runtime"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}