Limit Server Execution Time

On this page

Overview

timeoutMS Option
Timeout Inheritance
Overrides
Transactions
Client Encryption
Cursors
Cursor Lifetime Mode
Cursor Iteration Mode
API Documentation

Overview

When you use the Node.js driver to perform a server operation, you can also limit the duration allowed for the server to finish the operation. To do so, specify a client-side operation timeout (CSOT). The timeout applies to all steps needed to complete the operation, including server selection, connection checkout, and server-side execution. When the timeout expires, the Node.js driver raises a timeout exception.

Note

Experimental Feature

The CSOT feature is experimental and might change in future driver releases.

timeoutMS Option

To specify a timeout when connecting to a MongoDB deployment, set the timeoutMS connection option to the timeout length in milliseconds. You can do this in two ways: by passing an argument to the MongoClient constructor or through a parameter in your connection string.

The following code examples use the timeoutMS option to specify a timeout of 30 seconds:

const uri = "mongodb://<hostname:<port>";
const client = new MongoClient(uri, { timeoutMS: 30000 });

const uri = "mongodb://<hostname:<port>?timeoutMS=30000";
const client = new MongoClient(uri);

Note

The timeoutMS connection option takes precedence over the following options:

socketTimeoutMS
waitQueueTimeoutMS
wTimeoutMS
maxTimeMS
maxCommitTimeMS

When the CSOT feature is no longer experimental, the preceding options will be deprecated.

If you specify the timeoutMS option, the driver automatically applies the specified timeout per each server operation. The following code example specifies a timeout of 10 seconds at the client level, and then calls the insertOne() method:

const uri = "<connection string uri>";
const client = new MongoClient(uri, {
  timeoutMS: 10000
});
async function run() {
    try {
      const db = client.db("test-db");
      const coll = db.collection("test-collection");
      const result = await coll.insertOne({ name: "Yngwie" });
      console.log("Insert result:", result);
    } finally {
      await client.close();
    }
  }
  
run().catch(console.dir);

Timeout Inheritance

When you specify a timeoutMS option, the driver applies the timeout according to the same inheritance behaviors as the other Node.js driver options. The following table describes how the timeout value is inherited at each level:

Level	Inheritance Description
Operation	Takes the highest precedence and will override `timeoutMS` options set at any other level.
Transaction	Takes precedence over `timeoutMS` set at the session, collection, database, or client level.
Session	Applies to all transactions and operations within that session, unless the option is overridden by options set at those levels.
Database	Applies to all sessions and operations within that database, unless the option is overridden by options set at those levels.
Collection	Applies to all sessions and operations on that collection, unless the option is overridden by options set at those levels.
Client	Applies to all databases, collections, sessions, transactions, and operations within that client that do not otherwise specify `timeoutMS`.

For more information on overrides and specific options, see the Overrides section.

Overrides

The Node.js driver supports various levels of configuration to control the behavior and performance of database operations.

You can specify a timeoutMS option at the operation level to override the client-level configuration for a specific operation. This allows you to customize timeouts based on the needs of individual queries.

The following example demonstrates how an operation-level timeoutMS configuration can override a client-level timeoutMS configuration:

// Creates a new MongoClient with a client-level timeoutMS configuration
const uri = "<connection string uri>";
const client = new MongoClient(uri, {
  // Client-level timeout: 15 seconds
  timeoutMS: 15000
});
async function run() {
  try {
    const db = client.db("test-db");
    const coll = db.collection("test-collection");
    // Performs a query operation with an operation-level timeoutMS configuration
    const docs = await coll.find({}, 
        // Operation-level timeout: 10 seconds
        { timeoutMS: 10000 })
        .toArray(); 
    console.log(docs);
  } finally {
    await client.close();
  }
}
run().catch(console.dir);

Transactions

When you create a new ClientSession instance to implement a transaction, use the defaultTimeoutMS option. You can set defaultTimeoutMS to specify the timeoutMS values to use for:

If you do not specify defaultTimeoutMS, the driver uses the timeoutMS value set on the parent MongoClient.

You cannot override defaultTimeoutMS by setting the timeoutMS option on an operation in a transaction session provided by the withTransaction() callback. Doing so throws an error.

Client Encryption

When you use Client-Side Field Level Encryption (CSFLE), the driver uses the timeoutMS option to limit the time allowed for encryption and decryption operations.

If you specify the timeoutMS option when you construct a ClientEncryption instance, it controls the lifetime of all operations performed on that instance. If you do not provide timeoutMS, the instance inherits the timeoutMS setting from the MongoClient used in the ClientEncryption constructor.

If you set timeoutMS on both the client and directly in ClientEncryption, the value provided to ClientEncryption takes precedence.

Cursors

Cursors offer configurable timeout settings when using the CSOT feature. You can adjust cursor handling by configuring either the cursor lifetime or cursor iteration mode if needed. To configure the mode, set the timeoutMode option to cursorLifetime, which is the default, or iteration.

Cursor Lifetime Mode

The cursor lifetime mode uses timeoutMS to limit the entire lifetime of a cursor. In this mode, the initialization of the cursor and all subsequent calls to the cursor methods must complete within the limit specified by the timeoutMS option. All documents must be returned within this limit. Otherwise, the cursor's lifetime expires and a timeout error occurs.

When you close a cursor by calling the toArray() or close() method, the timeout resets for the killCursors command to ensure server-side resources are cleaned up.

The following example shows how to set the timeoutMS option to ensure that the cursor is initialized and all documents are retrieved within 10 seconds:

const docs = await collection.find({}, {timeoutMS: 10000}).toArray();

Cursor Iteration Mode

The cursor iteration mode uses the timeoutMS option to limit each call to the next(), hasNext(), or tryNext() method. The timeout refreshes after each call completes. This is the default mode for all tailable cursors, such as the tailable cursors returned by the find() method on capped collections or change streams.

The following code example iterates over documents in the mflix collection using a cursor with the timeoutMode set to iteration, and then fetches and logs the imdb_url for each movie document:

for await (const movie of mflix.find({}, { timeoutMode: 'iteration' })) {
   const imdbResponse = await fetch(movie.imdb_url);
   console.log(await imdbResponse.text());
}

API Documentation

To learn more about using timeouts with the Node.js driver, see the following API documentation:

Back

SOCKS5 Proxy Support

Stable API