mongodb/node-mongodb-native · error · TimeoutError

Timed out

Error message

Timed out

What it means

Thrown by Timeout.throwIfExpired() when the timeout has already elapsed (timedOut flag is true) and a code path checks synchronously rather than awaiting the promise. This is the internal TimeoutError class (a Promise subclass), distinct from the public MongoOperationTimeoutError. It signals that an operation's deadline passed before work could proceed.

Solutions

1. Increase the relevant timeout (serverSelectionTimeoutMS, socketTimeoutMS, or timeoutMS) to accommodate your deployment's latency.
2. Verify the MongoDB instance is reachable and healthy (network, firewall, DNS).
3. Scale the connection pool or reduce concurrent load if checkout timeouts are the cause.

Example fix

// before
const client = new MongoClient(uri); // default 30s server selection

// after
const client = new MongoClient(uri, { serverSelectionTimeoutMS: 60000 });

import { MongoOperationTimeoutError } from 'mongodb';
function isTimeoutError(e: unknown): boolean {
  return e instanceof Error && (e.name === 'TimeoutError' || e instanceof MongoOperationTimeoutError);
}

let attempt = 0;
while (attempt < 3) {
  try {
    return await collection.findOne(filter, { timeoutMS: 5000 });
  } catch (e) {
    if (isTimeoutError(e) && attempt < 2) { attempt++; continue; }
    throw e;
  }
}

When it happens

Trigger: Any operation that uses a TimeoutContext and calls throwIfExpired() after the deadline elapses, e.g. server selection, connection checkout, or command execution when the configured timeoutMS or socketTimeoutMS has run out. Most commonly surfaces to users wrapped as a driver-level timeout error.

Common situations: Slow or unreachable MongoDB deployments where serverSelectionTimeoutMS (default 30s) expires during connect, or when timeoutMS/CSOT is enabled and an operation cannot complete in the remaining budget. Network latency spikes or overloaded connection pools also trigger it.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• [Azure KMS]
• KMS request timed out
• ${MongoError.buildErrorMessage(cause)}
• Server roundtrip time is greater than the time remaining
• Timed out during server selection

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

Appendix: 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 dce7939f86)