mongodb/node-mongodb-native · error · MongoRuntimeError

Unrecognized options

Error message

Unrecognized options

What it means

Thrown by TimeoutContext.create() when the options object matches neither the CSOT shape (requires timeoutMS + serverSelectionTimeoutMS numbers) nor the Legacy shape (requires serverSelectionTimeoutMS + waitQueueTimeoutMS numbers). This is an internal factory used during operation execution to build the timeout context; reaching this branch means the options did not carry the required numeric fields.

Solutions

1. Avoid manually constructing or mutating the client's internal options object; use documented MongoClientOptions only.
2. Ensure you are on a compatible, non-corrupted driver version with a clean install (rm -rf node_modules && npm install).
3. If using a driver fork or wrapper, verify it passes through serverSelectionTimeoutMS and waitQueueTimeoutMS correctly.

try {
  await client.db('test').command({ ping: 1 });
} catch (e) {
  if (e instanceof MongoRuntimeError && /Unrecognized options/.test(e.message)) {
    // rebuild client with standard MongoClientOptions; report driver version mismatch
  } else throw e;
}

When it happens

Trigger: Internal driver code calling TimeoutContext.create() with an options object missing required numeric fields (serverSelectionTimeoutMS, waitQueueTimeoutMS, or timeoutMS). Not typically user-facing unless client options were constructed incorrectly at a low level.

Common situations: Rarely seen by end users. May surface if a custom MongoClient subclass or middleware strips timeout-related options from the client's internal configuration, or during driver version mismatches where the internal option shape changed.

Related errors

• Cannot create a Timeout with a negative duration
• Cannot use maxTimeMS with timeoutMS for explain commands.
• Descriptors missing a type must define a transform
• No workflow provided to the OIDC auth provider.
• Option "hostAddress" is required

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

Appendix: source

Thrown at src/timeout.ts:170

function isCSOTTimeoutContextOptions(v: unknown): v is CSOTTimeoutContextOptions {
  return (
    v != null &&
    typeof v === 'object' &&
    'serverSelectionTimeoutMS' in v &&
    typeof v.serverSelectionTimeoutMS === 'number' &&
    'timeoutMS' in v &&
    typeof v.timeoutMS === 'number'
  );
}

/** @internal */
export abstract class TimeoutContext {
  static create(options: TimeoutContextOptions): TimeoutContext {
    if (options.session?.timeoutContext != null) return options.session?.timeoutContext;
    if (isCSOTTimeoutContextOptions(options)) return new CSOTTimeoutContext(options);
    else if (isLegacyTimeoutContextOptions(options)) return new LegacyTimeoutContext(options);
    else throw new MongoRuntimeError('Unrecognized options');
  }

  abstract get maxTimeMS(): number | null;

  abstract get serverSelectionTimeout(): Timeout | null;

  abstract get connectionCheckoutTimeout(): Timeout | null;

  abstract get clearServerSelectionTimeout(): boolean;

  abstract get timeoutForSocketWrite(): Timeout | null;

  abstract get timeoutForSocketRead(): Timeout | null;

  abstract csotEnabled(): this is CSOTTimeoutContext;

  abstract refresh(): void;

View on GitHub (pinned to dce7939f86)