Client Side Operation Timeout

PyMongo 4.2 introduced timeout() and the timeoutMS URI and keyword argument to MongoClient. These features allow applications to more easily limit the amount of time that one or more operations can execute before control is returned to the app. This timeout applies to all of the work done to execute the operation, including but not limited to server selection, connection checkout, serialization, and server-side execution.

Basic Usage

The following example uses timeout() to configure a 10-second timeout for an insert_one() operation:

import pymongo
with pymongo.timeout(10):
    coll.insert_one({"name": "Nunu"})

The timeout() applies to all pymongo operations within the block. The following example ensures that both the insert and the find complete within 10 seconds total, or raise a timeout error:

with pymongo.timeout(10):
    coll.insert_one({"name": "Nunu"})
    coll.find_one({"name": "Nunu"})

When nesting timeout(), the nested deadline is capped by the outer deadline. The deadline can only be shortened, not extended. When exiting the block, the previous deadline is restored:

with pymongo.timeout(5):
    coll.find_one()  # Uses the 5 second deadline.
    with pymongo.timeout(3):
        coll.find_one() # Uses the 3 second deadline.
    coll.find_one()  # Uses the original 5 second deadline.
    with pymongo.timeout(10):
        coll.find_one()  # Still uses the original 5 second deadline.
    coll.find_one()  # Uses the original 5 second deadline.

Timeout errors

When the timeout() with-statement is entered, a deadline is set for the entire block. When that deadline is exceeded, any blocking pymongo operation will raise a timeout exception. For example:

try:
    with pymongo.timeout(10):
        coll.insert_one({"name": "Nunu"})
        time.sleep(10)
        # The deadline has now expired, the next operation will raise
        # a timeout exception.
        coll.find_one({"name": "Nunu"})
except PyMongoError as exc:
    if exc.timeout:
        print(f"block timed out: {exc!r}")
    else:
        print(f"failed with non-timeout error: {exc!r}")

The pymongo.errors.PyMongoError.timeout property (added in PyMongo 4.2) will be True when the error was caused by a timeout and False otherwise.

The timeoutMS URI option

PyMongo 4.2 also added support for the timeoutMS URI and keyword argument to MongoClient. When this option is configured, the client will automatically apply the timeout to each API call. For example:

client = MongoClient("mongodb://localhost/?timeoutMS=10000")
coll = client.test.test
coll.insert_one({"name": "Nunu"})  # Uses a 10-second timeout.
coll.find_one({"name": "Nunu"})  # Also uses a 10-second timeout.

The above is roughly equivalent to:

client = MongoClient()
coll = client.test.test
with pymongo.timeout(10):
    coll.insert_one({"name": "Nunu"})
with pymongo.timeout(10):
    coll.find_one({"name": "Nunu"})

pymongo.timeout overrides timeoutMS

timeout() overrides timeoutMS; within a timeout() block a client’s timeoutMS option is ignored:

client = MongoClient("mongodb://localhost/?timeoutMS=10000")
coll = client.test.test
coll.insert_one({"name": "Nunu"})  # Uses the client's 10-second timeout.
# pymongo.timeout overrides the client's timeoutMS.
with pymongo.timeout(20):
    coll.insert_one({"name": "Nunu"})  # Uses the 20-second timeout.
with pymongo.timeout(5):
    coll.find_one({"name": "Nunu"})  # Uses the 5-second timeout.

pymongo.timeout is thread safe

timeout() is thread safe; the timeout only applies to current thread and multiple threads can configure different timeouts in parallel.

pymongo.timeout is asyncio safe

timeout() is asyncio safe; the timeout only applies to current Task and multiple Tasks can configure different timeouts concurrently. timeout() can be used identically in Motor, for example:

import motor.motor_asyncio
client = motor.motor_asyncio.AsyncIOMotorClient()
coll = client.test.test
with pymongo.timeout(10):
    await coll.insert_one({"name": "Nunu"})
    await coll.find_one({"name": "Nunu"})

Troubleshooting

There are many timeout errors that can be raised depending on when the timeout expires. In code, these can be identified with the pymongo.errors.PyMongoError.timeout property. Some specific timeout errors examples are described below.

When the client was unable to find an available server to run the operation within the given timeout:

pymongo.errors.ServerSelectionTimeoutError: No servers found yet, Timeout: -0.00202266700216569s, Topology Description: <TopologyDescription id: 63698e87cebfd22ab1bd2ae0, topology_type: Unknown, servers: [<ServerDescription ('localhost', 27017) server_type: Unknown, rtt: None>]>

When either the client was unable to establish a connection within the given timeout or the operation was sent but the server was not able to respond in time:

pymongo.errors.NetworkTimeout: localhost:27017: timed out

When the server cancelled the operation because it exceeded the given timeout. Note that the operation may have partially completed on the server (depending on the operation):

pymongo.errors.ExecutionTimeout: operation exceeded time limit, full error: {'ok': 0.0, 'errmsg': 'operation exceeded time limit', 'code': 50, 'codeName': 'MaxTimeMSExpired'}

When the client cancelled the operation because it was not possible to complete within the given timeout:

pymongo.errors.ExecutionTimeout: operation would exceed time limit, remaining timeout:0.00196 <= network round trip time:0.00427

When the client attempted a write operation but the server could not replicate that write (according to the configured write concern) within the given timeout:

pymongo.errors.WTimeoutError: operation exceeded time limit, full error: {'code': 50, 'codeName': 'MaxTimeMSExpired', 'errmsg': 'operation exceeded time limit', 'errInfo': {'writeConcern': {'w': 1, 'wtimeout': 0}}}

The same error as above but for insert_many() or bulk_write():

pymongo.errors.BulkWriteError: batch op errors occurred, full error: {'writeErrors': [], 'writeConcernErrors': [{'code': 50, 'codeName': 'MaxTimeMSExpired', 'errmsg': 'operation exceeded time limit', 'errInfo': {'writeConcern': {'w': 1, 'wtimeout': 0}}}], 'nInserted': 2, 'nUpserted': 0, 'nMatched': 0, 'nModified': 0, 'nRemoved': 0, 'upserted': []}