mongodb/node-mongodb-native · error · TimeoutError

Timed out

Error message

Timed out

What it means

Thrown by the @internal Timeout.throwIfExpired() when the timeout has already fired (timedOut === true). It produces a TimeoutError with message 'Timed out' and the configured duration. This is the synchronous check counterpart to awaiting the Timeout promise's rejection. The internal Timeout class is shared by both legacy and CSOT timeout contexts.

Source

Thrown at src/timeout.ts:110

  }

  /**
   * Clears the underlying timeout. This method is idempotent
   */
  clear(): void {
    clearTimeout(this.id);
    this.id = undefined;
    this.timedOut = false;
    this.cleared = true;
  }

  throwIfExpired(): void {
    if (this.timedOut) {
      // This method is invoked when someone wants to throw immediately instead of await the result of this promise
      // Since they won't be handling the rejection from the promise (because we're about to throw here)
      // attach handling to prevent this from bubbling up to Node.js
      this.then(undefined, squashError);
      throw new TimeoutError('Timed out', { duration: this.duration });
    }
  }

  public static expires(duration: number, unref?: true): Timeout {
    return new Timeout(undefined, { duration, unref });
  }

  static override reject(rejection?: Error): Timeout {
    return new Timeout(undefined, { duration: 0, unref: true, rejection });
  }
}

/** @internal */
export type TimeoutContextOptions = (LegacyTimeoutContextOptions | CSOTTimeoutContextOptions) & {
  session?: ClientSession;
};

/** @internal */

View on GitHub (pinned to 3366c21a63)

Solutions

1. Increase the operation timeout (timeoutMS) or relevant socketTimeoutMS / serverSelectionTimeoutMS.
2. Reduce operation latency: add indexes, narrow queries, scale the cluster.
3. If seen unexpectedly, report it - throwIfExpired firing where the await path should have surfaced the error first can indicate a driver bug.

Example fix

// before
cursor.addCursorFlag('noCursorTimeout', true); // unrelated, does not help

// after - size the timeout to the workload
await coll.find({}, { timeoutMS: 60_000 }).toArray();

// user-side: size the timeout to the workload
const timeoutMS = estimatedOpMs * 2;
await coll.find({}, { timeoutMS }).toArray();

import { MongoOperationTimeoutError } from 'mongodb';
function isTimeoutError(e: unknown): boolean {
  return e instanceof MongoOperationTimeoutError ||
    (e != null && typeof e === 'object' && (e as any).name === 'TimeoutError');
}

try {
  await op();
} catch (e) {
  if (isTimeoutError(e)) {
    // optionally retry once with a larger timeoutMS, or surface to the user
  } else throw e;
}

When it happens

Trigger: Driver-internal code calling timeout.throwIfExpired() after the timeout already elapsed (e.g. between awaiting a connection and issuing a command). Not thrown directly by user-facing methods under normal use; users see MongoOperationTimeoutError wrappers instead.

Common situations: Slow operations where the deadline expires mid-flight; CSOT contexts checking expiry before each phase (server selection, checkout, socket write/read).

Related errors

• Cannot create a Timeout with a negative duration
• Unrecognized options
• Unreachable. If you are seeing this error, please file a tic
• Expired after ${this.timeoutMS}ms
• KMS request timed out

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