mongodb/node-mongodb-native · error · MongoRuntimeError

Unrecognized options

Error message

Unrecognized options

What it means

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.

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 3366c21a63)

Solutions

1. Ensure the options bag passed to TimeoutContext.create contains all required keys for either the CSOT or Legacy shape.
2. Upgrade the driver - this path is internal and the cause is almost always a driver bug; report it with the operation and options used.
3. If writing driver tests, use the helpers that construct TimeoutContextOptions rather than hand-building the object.

Example fix

// before (internal)
TimeoutContext.create({ serverSelectionTimeoutMS: 30000 }); // throws: missing waitQueueTimeoutMS / timeoutMS

// after
TimeoutContext.create({ serverSelectionTimeoutMS: 30000, waitQueueTimeoutMS: 120000 }); // legacy
// or
TimeoutContext.create({ timeoutMS: 10000, serverSelectionTimeoutMS: 30000 }); // CSOT

// internal: ensure required keys before creating a context
function isCSOT(o: any) {
  return typeof o?.timeoutMS === 'number' && typeof o?.serverSelectionTimeoutMS === 'number';
}
function isLegacy(o: any) {
  return typeof o?.serverSelectionTimeoutMS === 'number' && typeof o?.waitQueueTimeoutMS === 'number';
}
if (isCSOT(opts) || isLegacy(opts)) {
  TimeoutContext.create(opts);
}

When it happens

Trigger: 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.

Common situations: Driver bugs in timeout-context wiring; tests/mocks that build options bags by hand without all required keys; regressions after refactoring timeout option propagation.

Related errors

• Unreachable. If you are seeing this error, please file a tic
• Cannot create a Timeout with a negative duration
• Timed out
• KMS request timed out
• Unexpected HostAddress ${JSON.stringify(hostAddress)}

AI-assisted analysis of mongodb/node-mongodb-native@3366c21a63 (2026-08-04). Data as JSON: /data/errors/035b532f1201a792.json. Report an issue: GitHub.