Adaptive Timeouts in Database Drivers

Parent: Client Side Operations Timeout (CSOT) · Published reference · snapshot 2026-10-15

Depth-first rabbithole dossier for Adaptive Timeouts in Database Drivers; source-anchored research pack.

These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.

How it works

[low] When the timeout expires, the Node.js driver raises a timeout exception. Sources: https://www.mongodb.com/docs/drivers/node/current/connect/connection-options/csot.md [source]
[low] A best practice is to set both connection and request timeouts on any remote call or cross-process call, even on the same box. Sources: https://builder.aws.com/content/3EumjoZascWd1oZiEgL8ORlv3qE/timeouts-retries-and-backoff-with-jitter [source]

Measurements and reference values

[low] A best practice for choosing timeouts is to start with downstream service latency metrics and choose an acceptable false timeout rate, such as 0.1% corresponding to p99.9 latency. Sources: https://builder.aws.com/content/3EumjoZascWd1oZiEgL8ORlv3qE/timeouts-retries-and-backoff-with-jitter [source]

Problems, failure modes and limitations

[low] Drivers MUST return a timeout error without sending the message if `minRoundTripTime` exceeds the remaining `timeoutMS` to prevent likely socket timeouts. Sources: https://raw.githubusercontent.com/mongodb/specifications/master/source/client-side-operations-timeout/client-side-operations-timeout.md [source]
[high] Drivers MUST ignore deprecated timeout options if `timeoutMS` is set on the operation or inherited from the client. Sources: https://raw.githubusercontent.com/mongodb/specifications/master/source/client-side-operations-timeout/client-side-operations-timeout.md, https://www.mongodb.com/docs/drivers/node/current/connect/connection-options/csot.md [source]
[low] If `timeoutMS` is set, drivers MUST retry operations as many times as possible before the timeout expires or a non-retryable error occurs. Sources: https://raw.githubusercontent.com/mongodb/specifications/master/source/client-side-operations-timeout/client-side-operations-timeout.md [source]
[low] You cannot override `defaultTimeoutMS` by setting `timeoutMS` on an operation in a transaction session provided by `withTransaction()`, as this throws an error. Sources: https://www.mongodb.com/docs/drivers/node/current/connect/connection-options/csot.md [source]
[low] Cursor lifetime mode uses `timeoutMS` to limit the entire cursor lifetime, while iteration mode limits each `next()`, `hasNext()`, or `tryNext()` call with the timeout refreshing after each completion. Sources: https://www.mongodb.com/docs/drivers/node/current/connect/connection-options/csot.md [source]
[low] Some timeout implementations fail to cover all remote calls like DNS or TLS handshakes, and Linux's SO_RCVTIMEO has disadvantages making it unsuitable for end-to-end socket timeouts. Sources: https://builder.aws.com/content/3EumjoZascWd1oZiEgL8ORlv3qE/timeouts-retries-and-backoff-with-jitter [source]

Facts and statements

[low] If `timeoutMS` is set, drivers MUST use `min(serverSelectionTimeoutMS, remaining timeoutMS)` as the `computedServerSelectionTimeout`. Sources: https://raw.githubusercontent.com/mongodb/specifications/master/source/client-side-operations-timeout/client-side-operations-timeout.md [source]
[low] The `serverSelectionTryOnce` option MUST be true by default, and drivers MUST enforce a server selection timeout if it is false or in multi-threaded drivers. Sources: https://raw.githubusercontent.com/mongodb/specifications/master/source/server-selection/server-selection.md [source]
[high] The CSOT feature is experimental and may change in future driver releases, with specific fixes tracked in PYTHON-3616 (4.4), GODRIVER-2762 (2.0.0), and NODE-5825 (6.6.0). (verified as of 2026-10-15) Sources: https://jira.mongodb.org/browse/DRIVERS-2035, https://www.mongodb.com/docs/drivers/node/current/connect/connection-options/csot.md [source]
[low] The `timeoutMS` applies to all steps of an operation, including server selection, connection checkout, and server-side execution. Sources: https://www.mongodb.com/docs/drivers/node/current/connect/connection-options/csot.md [source]
[low] To specify a timeout, set the `timeoutMS` connection option; if `defaultTimeoutMS` is not specified, the driver uses the `timeoutMS` from the parent `MongoClient`. Sources: https://www.mongodb.com/docs/drivers/node/current/connect/connection-options/csot.md [source]
[low] The `timeoutMode` option configures cursor timeout behavior, defaulting to `cursorLifetime` or allowing `iteration` mode. Sources: https://www.mongodb.com/docs/drivers/node/current/connect/connection-options/csot.md [source]
[low] Closing a cursor via `toArray()` or `close()` resets the timeout for the `killCursors` command to ensure server-side resource cleanup. Sources: https://www.mongodb.com/docs/drivers/node/current/connect/connection-options/csot.md [source]
[medium] Drivers use the minimum RTT from the last 10 samples for CSOT calculations, using 0 until at least 2 samples are recorded. Sources: https://raw.githubusercontent.com/mongodb/specifications/master/source/client-side-operations-timeout/client-side-operations-timeout.md, https://jira.mongodb.org/browse/DRIVERS-2035 [source]
[low] It is preferred to use built-in timeouts from well-tested clients, paying careful attention to the exact meaning of timeout socket options and the work being done. Sources: https://builder.aws.com/content/3EumjoZascWd1oZiEgL8ORlv3qE/timeouts-retries-and-backoff-with-jitter [source]

Related concepts

Drivers — is a part of Adaptive Timeouts in Database Drivers
Timeouts — is a part of Adaptive Timeouts in Database Drivers

Children

No children recorded.

← the whole tree · 3D view· how to read this page