From b077589d261e935e96b121e25a303ac6156034eb Mon Sep 17 00:00:00 2001
From: Valentin Kovalenko <valentin.kovalenko@mongodb.com>
Date: Fri, 17 Apr 2026 16:19:07 -0600
Subject: [PATCH 1/3] Add `maxAdaptiveRetries` API

JAVA-6141
---
 .../main/com/mongodb/ConnectionString.java    |  50 ++++--
 .../main/com/mongodb/MongoClientSettings.java | 143 +++++++++++++++++-
 .../src/main/com/mongodb/MongoException.java  |  24 ++-
 .../mongodb/AbstractConnectionStringTest.java |   3 +
 .../com/mongodb/ConnectionStringUnitTest.java |  56 ++++---
 .../MongoClientSettingsSpecification.groovy   |  28 +++-
 .../kotlin/client/coroutine/ClientSession.kt  |   4 +
 .../mongodb/kotlin/client/ClientSession.kt    |   7 +
 .../main/com/mongodb/MongoClientOptions.java  |  56 ++++++-
 .../src/main/com/mongodb/MongoClientURI.java  |  21 +--
 .../MongoClientOptionsSpecification.groovy    |  23 +++
 .../MongoClientURISpecification.groovy        |  35 ++++-
 .../reactivestreams/client/ClientSession.java |   4 +
 .../scala/org/mongodb/scala/package.scala     |  30 ++++
 .../com/mongodb/client/ClientSession.java     |   8 +
 15 files changed, 426 insertions(+), 66 deletions(-)

diff --git a/driver-core/src/main/com/mongodb/ConnectionString.java b/driver-core/src/main/com/mongodb/ConnectionString.java
index 659e8fd02aa..39e60e03b5b 100644
--- a/driver-core/src/main/com/mongodb/ConnectionString.java
+++ b/driver-core/src/main/com/mongodb/ConnectionString.java
@@ -17,6 +17,7 @@
 package com.mongodb;
 
 import com.mongodb.annotations.Alpha;
+import com.mongodb.annotations.Beta;
 import com.mongodb.annotations.Reason;
 import com.mongodb.connection.ClusterSettings;
 import com.mongodb.connection.ConnectionPoolSettings;
@@ -264,14 +265,17 @@
  * <p>SRV configuration:</p>
  * <ul>
  * <li>{@code srvServiceName=string}: The SRV service name. See {@link ClusterSettings#getSrvServiceName()} for details.</li>
- * <li>{@code srvMaxHosts=number}: The maximum number of hosts from the SRV record to connect to.</li>
+ * <li>{@code srvMaxHosts=n}: The maximum number of hosts from the SRV record to connect to.</li>
  * </ul>
  * <p>General configuration:</p>
  * <ul>
- * <li>{@code retryWrites=true|false}. If true the driver will retry supported write operations if they fail due to a network error.
- *  Defaults to true.</li>
- * <li>{@code retryReads=true|false}. If true the driver will retry supported read operations if they fail due to a network error.
- *  Defaults to true.</li>
+ * <li>{@code retryWrites=true|false}: Whether attempts to execute write commands should be retried if they fail due to a retryable error.
+ *  Defaults to true. See also {@code maxAdaptiveRetries}.</li>
+ * <li>{@code retryReads=true|false}: Whether attempts to execute read commands should be retried if they fail due to a retryable error.
+ *  Defaults to true. See also {@code maxAdaptiveRetries}.</li>
+ * <li>{@code maxAdaptiveRetries=n}: This is {@linkplain Beta Beta API}.
+ * The maximum number of retry attempts when encountering a retryable overload error.
+ * See {@link MongoClientSettings.Builder#maxAdaptiveRetries(Integer)} for more information.</li>
  * <li>{@code uuidRepresentation=unspecified|standard|javaLegacy|csharpLegacy|pythonLegacy}.  See
  * {@link MongoClientSettings#getUuidRepresentation()} for documentation of semantics of this parameter.  Defaults to "javaLegacy", but
  * will change to "unspecified" in the next major release.</li>
@@ -308,6 +312,7 @@ public class ConnectionString {
     private WriteConcern writeConcern;
     private Boolean retryWrites;
     private Boolean retryReads;
+    private Integer maxAdaptiveRetries;
     private ReadConcern readConcern;
 
     private Integer minConnectionPoolSize;
@@ -558,6 +563,7 @@ public ConnectionString(final String connectionString, @Nullable final DnsClient
         GENERAL_OPTIONS_KEYS.add("servermonitoringmode");
         GENERAL_OPTIONS_KEYS.add("retrywrites");
         GENERAL_OPTIONS_KEYS.add("retryreads");
+        GENERAL_OPTIONS_KEYS.add("maxadaptiveretries");
 
         GENERAL_OPTIONS_KEYS.add("appname");
 
@@ -706,6 +712,12 @@ private void translateOptions(final Map<String, List<String>> optionsMap) {
                 case "retryreads":
                     retryReads = parseBoolean(value, "retryreads");
                     break;
+                case "maxadaptiveretries":
+                    maxAdaptiveRetries = parseInteger(value, "maxadaptiveretries");
+                    if (maxAdaptiveRetries < 0) {
+                        throw new IllegalArgumentException("maxAdaptiveRetries must be >= 0");
+                    }
+                    break;
                 case "uuidrepresentation":
                     uuidRepresentation = createUuidRepresentation(value);
                     break;
@@ -1455,13 +1467,15 @@ public WriteConcern getWriteConcern() {
     }
 
     /**
-     * <p>Gets whether writes should be retried if they fail due to a network error</p>
-     *
+     * Gets whether attempts to execute write commands should be retried if they fail due to a retryable error.
+     * See {@link MongoClientSettings.Builder#retryWrites(boolean)} for more information.
+     * <p>
      * The name of this method differs from others in this class so as not to conflict with the now removed
      * getRetryWrites() method, which returned a primitive {@code boolean} value, and didn't allow callers to differentiate
      * between a false value and an unset value.
      *
      * @return the retryWrites value, or null if unset
+     * @see #getMaxAdaptiveRetries()
      * @since 3.9
      * @mongodb.server.release 3.6
      */
@@ -1471,9 +1485,11 @@ public Boolean getRetryWritesValue() {
     }
 
     /**
-     * <p>Gets whether reads should be retried if they fail due to a network error</p>
+     * Gets whether attempts to execute read commands should be retried if they fail due to a retryable error.
+     * See {@link MongoClientSettings.Builder#retryReads(boolean)} for more information.
      *
-     * @return the retryWrites value
+     * @return the retryReads value
+     * @see #getMaxAdaptiveRetries()
      * @since 3.11
      * @mongodb.server.release 3.6
      */
@@ -1482,6 +1498,19 @@ public Boolean getRetryReads() {
         return retryReads;
     }
 
+    /**
+     * Gets the maximum number of retry attempts when encountering a retryable overload error.
+     * See {@link MongoClientSettings.Builder#maxAdaptiveRetries(Integer)} for more information.
+     *
+     * @return The {@code maxAdaptiveRetries} value.
+     * @since 5.7
+     */
+    @Beta(Reason.CLIENT)
+    @Nullable
+    public Integer getMaxAdaptiveRetries() {
+        return maxAdaptiveRetries;
+    }
+
     /**
      * Gets the minimum connection pool size specified in the connection string.
      * @return the minimum connection pool size
@@ -1795,6 +1824,7 @@ public boolean equals(final Object o) {
                 && Objects.equals(writeConcern, that.writeConcern)
                 && Objects.equals(retryWrites, that.retryWrites)
                 && Objects.equals(retryReads, that.retryReads)
+                && Objects.equals(maxAdaptiveRetries, that.maxAdaptiveRetries)
                 && Objects.equals(readConcern, that.readConcern)
                 && Objects.equals(minConnectionPoolSize, that.minConnectionPoolSize)
                 && Objects.equals(maxConnectionPoolSize, that.maxConnectionPoolSize)
@@ -1826,7 +1856,7 @@ public boolean equals(final Object o) {
     @Override
     public int hashCode() {
         return Objects.hash(credential, isSrvProtocol, hosts, database, collection, directConnection, readPreference,
-                writeConcern, retryWrites, retryReads, readConcern, minConnectionPoolSize, maxConnectionPoolSize, maxWaitTime,
+                writeConcern, retryWrites, retryReads, maxAdaptiveRetries, readConcern, minConnectionPoolSize, maxConnectionPoolSize, maxWaitTime,
                 maxConnectionIdleTime, maxConnectionLifeTime, maxConnecting, connectTimeout, timeout, socketTimeout, sslEnabled,
                 sslInvalidHostnameAllowed, requiredReplicaSetName, serverSelectionTimeout, localThreshold, heartbeatFrequency,
                 serverMonitoringMode, applicationName, compressorList, uuidRepresentation, srvServiceName, srvMaxHosts, proxyHost,
diff --git a/driver-core/src/main/com/mongodb/MongoClientSettings.java b/driver-core/src/main/com/mongodb/MongoClientSettings.java
index 41c5f73a1d7..1e013ff3cc0 100644
--- a/driver-core/src/main/com/mongodb/MongoClientSettings.java
+++ b/driver-core/src/main/com/mongodb/MongoClientSettings.java
@@ -17,6 +17,7 @@
 package com.mongodb;
 
 import com.mongodb.annotations.Alpha;
+import com.mongodb.annotations.Beta;
 import com.mongodb.annotations.Immutable;
 import com.mongodb.annotations.NotThreadSafe;
 import com.mongodb.annotations.Reason;
@@ -93,6 +94,8 @@ public final class MongoClientSettings {
     private final WriteConcern writeConcern;
     private final boolean retryWrites;
     private final boolean retryReads;
+    @Nullable
+    private final Integer maxAdaptiveRetries;
     private final ReadConcern readConcern;
     private final MongoCredential credential;
     private final TransportSettings transportSettings;
@@ -214,6 +217,8 @@ public static final class Builder {
         private WriteConcern writeConcern = WriteConcern.ACKNOWLEDGED;
         private boolean retryWrites = true;
         private boolean retryReads = true;
+        @Nullable
+        private Integer maxAdaptiveRetries;
         private ReadConcern readConcern = ReadConcern.DEFAULT;
         private CodecRegistry codecRegistry = MongoClientSettings.getDefaultCodecRegistry();
         private TransportSettings transportSettings;
@@ -255,6 +260,7 @@ private Builder(final MongoClientSettings settings) {
             writeConcern = settings.getWriteConcern();
             retryWrites = settings.getRetryWrites();
             retryReads = settings.getRetryReads();
+            maxAdaptiveRetries = settings.getMaxAdaptiveRetries();
             readConcern = settings.getReadConcern();
             credential = settings.getCredential();
             uuidRepresentation = settings.getUuidRepresentation();
@@ -314,6 +320,9 @@ public Builder applyConnectionString(final ConnectionString connectionString) {
             if (retryReadsValue != null) {
                 retryReads = retryReadsValue;
             }
+            if (connectionString.getMaxAdaptiveRetries() != null) {
+                maxAdaptiveRetries = connectionString.getMaxAdaptiveRetries();
+            }
             if (connectionString.getUuidRepresentation() != null) {
                 uuidRepresentation = connectionString.getUuidRepresentation();
             }
@@ -428,13 +437,24 @@ public Builder writeConcern(final WriteConcern writeConcern) {
         }
 
         /**
-         * Sets whether writes should be retried if they fail due to a network error.
+         * Sets whether attempts to execute write commands should be retried if they fail due to a retryable error.
+         * <p>
+         * The errors {@linkplain MongoException#hasErrorLabel(String) having}
+         * the {@value MongoException#RETRYABLE_ERROR_LABEL} label are not the only ones considered retryable here:
+         * unlike applications, which may retry operations, the driver retries commands, which gives it more control
+         * and allows it to safely retry attempts failed due to a broader set of errors
+         * than what applications may {@linkplain MongoException#RETRYABLE_ERROR_LABEL safely retry}.
+         * <p>
+         * For more information on how transactions affect retries,
+         * see the documentation of the {@value MongoException#TRANSIENT_TRANSACTION_ERROR_LABEL},
+         * {@value MongoException#UNKNOWN_TRANSACTION_COMMIT_RESULT_LABEL} error labels.
          *
          * <p>Starting with the 3.11.0 release, the default value is true</p>
          *
-         * @param retryWrites sets if writes should be retried if they fail due to a network error.
+         * @param retryWrites sets if write commands should be retried if they fail due to a retryable error.
          * @return this
          * @see #getRetryWrites()
+         * @see #maxAdaptiveRetries(Integer)
          * @mongodb.server.release 3.6
          */
         public Builder retryWrites(final boolean retryWrites) {
@@ -443,11 +463,24 @@ public Builder retryWrites(final boolean retryWrites) {
         }
 
         /**
-         * Sets whether reads should be retried if they fail due to a network error.
+         * Sets whether attempts to execute read commands should be retried if they fail due to a retryable error.
+         * <p>
+         * The errors {@linkplain MongoException#hasErrorLabel(String) having}
+         * the {@value MongoException#RETRYABLE_ERROR_LABEL} label are not the only ones considered retryable here:
+         * unlike applications, which may retry operations, the driver retries commands, which gives it more control
+         * and allows it to safely retry attempts failed due to a broader set of errors
+         * than what applications may {@linkplain MongoException#RETRYABLE_ERROR_LABEL safely retry}.
+         * <p>
+         * For more information on how transactions affect retries,
+         * see the documentation of the {@value MongoException#TRANSIENT_TRANSACTION_ERROR_LABEL},
+         * {@value MongoException#UNKNOWN_TRANSACTION_COMMIT_RESULT_LABEL} error labels.
+         * <p>
+         * Default is {@code true}.
          *
-         * @param retryReads sets if reads should be retried if they fail due to a network error.
+         * @param retryReads sets if read commands should be retried if they fail due to a retryable error.
          * @return this
          * @see #getRetryReads()
+         * @see #maxAdaptiveRetries(Integer)
          * @since 3.11
          * @mongodb.server.release 3.6
          */
@@ -456,6 +489,76 @@ public Builder retryReads(final boolean retryReads) {
             return this;
         }
 
+        /**
+         * Sets the maximum number of retry attempts when executing a command and encountering
+         * an error {@linkplain MongoException#hasErrorLabel(String) having}
+         * the {@value MongoException#SYSTEM_OVERLOADED_ERROR_LABEL} and {@value MongoException#RETRYABLE_ERROR_LABEL} labels.
+         * Such errors are referred to as retryable overload errors.
+         * <p>
+         * Default is {@code null}, implies the value 2 and the above retry behavior. The implied value and behavior may change in
+         * the future in a <a href="https://semver.org/spec/v2.0.0.html#summary">minor version</a>.
+         * This means, there is no guarantee that not setting a value is equivalent to setting the value 2.
+         * The value 0 results in not retrying the attempts failed due to retryable overload errors.
+         *
+         * <table>
+         *     <caption>Interactions with {@link #retryWrites(boolean)}/{@link #retryReads(boolean)}</caption>
+         *     <thead>
+         *         <tr>
+         *             <th>Command kind</th>
+         *             <th>Interaction</th>
+         *         </tr>
+         *     </thead>
+         *     <tbody>
+         *         <tr>
+         *             <td style="vertical-align: top;">write</td>
+         *             <td>
+         *                 The attempts failed due to retryable overload errors are retried only if
+         *                 {@link #retryWrites(boolean)} is {@code true}.
+         *             </td>
+         *         </tr>
+         *         <tr>
+         *             <td style="vertical-align: top;">read</td>
+         *             <td>
+         *                 The attempts failed due to retryable overload errors are retried only if
+         *                 {@link #retryReads(boolean)} is {@code true}.
+         *                 <p>
+         *                 Executing a write operation, for example, {@code MongoCluster.bulkWrite},
+         *                 may involve executing not only write commands, but also read commands. In such a situation,
+         *                 just like in other situations, the behavior related to retries depends on
+         *                 the known kind of command, not on the kind of operation.
+         *             </td>
+         *         </tr>
+         *         <tr>
+         *             <td style="vertical-align: top;">unknown</td>
+         *             <td>
+         *                 The attempts failed due to retryable overload errors are retried only if
+         *                 {@link #retryWrites(boolean)} is {@code true} and {@link #retryReads(boolean)} is {@code true}.
+         *                 <p>
+         *                 The command kind is unknown when a command is executed via the {@code MongoDatabase.runCommand} operation.
+         *             </td>
+         *         </tr>
+         *     </tbody>
+         * </table>
+         *
+         * @param maxAdaptiveRetries Sets the maximum number of retry attempts when encountering a retryable overload error.
+         *
+         * @return {@code this}.
+         * @see #getMaxAdaptiveRetries()
+         * @mongodb.driver.manual reference/parameters/#mongodb-parameter-param.overloadAwareServerSelectionEnabled
+         * overloadAwareServerSelectionEnabled: the server-side counterpart, which is configured independently
+         * and affects the server behavior as opposed to the client behavior.
+         * @since 5.7
+         */
+        // TODO-BACKPRESSURE Valentin Document commands that we do not retry now, but should retry according to the spec.
+        @Beta(Reason.CLIENT)
+        public Builder maxAdaptiveRetries(@Nullable final Integer maxAdaptiveRetries) {
+            if (maxAdaptiveRetries != null) {
+                isTrueArgument("maxAdaptiveRetries >= 0", maxAdaptiveRetries >= 0);
+            }
+            this.maxAdaptiveRetries = maxAdaptiveRetries;
+            return this;
+        }
+
         /**
          * Sets the read concern.
          *
@@ -785,11 +888,14 @@ public WriteConcern getWriteConcern() {
     }
 
     /**
-     * Returns true if writes should be retried if they fail due to a network error or other retryable error.
+     * Returns whether attempts to execute write commands should be retried if they fail due to a retryable error.
+     * See {@link Builder#retryWrites(boolean)} for more information.
      *
      * <p>Starting with the 3.11.0 release, the default value is true</p>
      *
      * @return the retryWrites value
+     * @see Builder#retryWrites(boolean)
+     * @see #getMaxAdaptiveRetries()
      * @mongodb.server.release 3.6
      */
     public boolean getRetryWrites() {
@@ -797,9 +903,14 @@ public boolean getRetryWrites() {
     }
 
     /**
-     * Returns true if reads should be retried if they fail due to a network error or other retryable error. The default value is true.
+     * Returns whether attempts to execute read commands should be retried if they fail due to a retryable error.
+     * See {@link Builder#retryReads(boolean)} for more information.
+     * <p>
+     * Default is {@code true}.
      *
      * @return the retryReads value
+     * @see Builder#retryReads(boolean)
+     * @see #getMaxAdaptiveRetries()
      * @since 3.11
      * @mongodb.server.release 3.6
      */
@@ -807,6 +918,21 @@ public boolean getRetryReads() {
         return retryReads;
     }
 
+    /**
+     * Returns the maximum number of retry attempts when encountering a retryable overload error.
+     * See {@link Builder#maxAdaptiveRetries(Integer)} for more information.
+     *
+     * @return The maximum number of retry attempts when encountering a retryable overload error.
+     * @see Builder#maxAdaptiveRetries(Integer)
+     * @since 5.7
+     */
+    @Beta(Reason.CLIENT)
+    @Nullable
+    // TODO-BACKPRESSURE Valentin Use the `maxAdaptiveRetries` setting when retrying.
+    public Integer getMaxAdaptiveRetries() {
+        return maxAdaptiveRetries;
+    }
+
     /**
      * The read concern to use.
      *
@@ -1080,6 +1206,7 @@ public boolean equals(final Object o) {
         MongoClientSettings that = (MongoClientSettings) o;
         return retryWrites == that.retryWrites
                 && retryReads == that.retryReads
+                && Objects.equals(maxAdaptiveRetries, that.maxAdaptiveRetries)
                 && heartbeatSocketTimeoutSetExplicitly == that.heartbeatSocketTimeoutSetExplicitly
                 && heartbeatConnectTimeoutSetExplicitly == that.heartbeatConnectTimeoutSetExplicitly
                 && Objects.equals(readPreference, that.readPreference)
@@ -1109,7 +1236,7 @@ public boolean equals(final Object o) {
 
     @Override
     public int hashCode() {
-        return Objects.hash(readPreference, writeConcern, retryWrites, retryReads, readConcern, credential, transportSettings,
+        return Objects.hash(readPreference, writeConcern, retryWrites, retryReads, maxAdaptiveRetries, readConcern, credential, transportSettings,
                 commandListeners, codecRegistry, loggerSettings, clusterSettings, socketSettings,
                 heartbeatSocketSettings, connectionPoolSettings, serverSettings, sslSettings, applicationName, compressorList,
                 uuidRepresentation, serverApi, autoEncryptionSettings, heartbeatSocketTimeoutSetExplicitly,
@@ -1124,6 +1251,7 @@ public String toString() {
                 + ", writeConcern=" + writeConcern
                 + ", retryWrites=" + retryWrites
                 + ", retryReads=" + retryReads
+                + ", maxAdaptiveRetries=" + maxAdaptiveRetries
                 + ", readConcern=" + readConcern
                 + ", credential=" + credential
                 + ", transportSettings=" + transportSettings
@@ -1153,6 +1281,7 @@ private MongoClientSettings(final Builder builder) {
         readPreference = builder.readPreference;
         writeConcern = builder.writeConcern;
         retryWrites = builder.retryWrites;
+        maxAdaptiveRetries = builder.maxAdaptiveRetries;
         retryReads = builder.retryReads;
         readConcern = builder.readConcern;
         credential = builder.credential;
diff --git a/driver-core/src/main/com/mongodb/MongoException.java b/driver-core/src/main/com/mongodb/MongoException.java
index 2c585c93cf4..b15023b2374 100644
--- a/driver-core/src/main/com/mongodb/MongoException.java
+++ b/driver-core/src/main/com/mongodb/MongoException.java
@@ -36,42 +36,52 @@ public class MongoException extends RuntimeException {
 
     /**
      * An error label indicating that the exception can be treated as a transient transaction error.
+     * See the documentation linked below for more information.
      *
      * @see #hasErrorLabel(String)
+     * @mongodb.driver.manual core/transactions-in-applications/#std-label-transient-transaction-error TransientTransactionError
      * @since 3.8
-     * @mongodb.driver.manual core/transactions-in-applications/#std-label-transient-transaction-error
      */
     public static final String TRANSIENT_TRANSACTION_ERROR_LABEL = "TransientTransactionError";
 
     /**
      * An error label indicating that the exception can be treated as an unknown transaction commit result.
+     * See the documentation linked below for more information.
      *
      * @see #hasErrorLabel(String)
+     * @mongodb.driver.manual core/transactions-in-applications/#std-label-unknown-transaction-commit-result UnknownTransactionCommitResult
      * @since 3.8
-     * @mongodb.driver.manual core/transactions-in-applications/#std-label-unknown-transaction-commit-result
      */
     public static final String UNKNOWN_TRANSACTION_COMMIT_RESULT_LABEL = "UnknownTransactionCommitResult";
 
     /**
      * Server is overloaded and shedding load.
-     * If you retry, use exponential backoff because the server has indicated overload.
-     * This label on its own does not mean that the operation can be safely retried.
+     * If an application retries explicitly, it should use exponential backoff because the server has indicated overload.
+     * This label on its own does not mean that the operation can be {@linkplain #RETRYABLE_ERROR_LABEL safely retried}.
      *
      * @see #hasErrorLabel(String)
+     * @see MongoClientSettings.Builder#maxAdaptiveRetries(Integer)
+     * @mongodb.atlas.manual overload-errors/ Overload errors
      * @since 5.7
      * @mongodb.server.release 8.3
      */
-    // TODO-BACKPRESSURE Valentin Add a @mongodb.driver.manual link or something similar, see `content/atlas/source/overload-errors.txt` in https://github.com/10gen/docs-mongodb-internal/pull/17281
     public static final String SYSTEM_OVERLOADED_ERROR_LABEL = "SystemOverloadedError";
 
     /**
-     * The operation was not executed and is safe to retry.
+     * The operation is safe to retry, that is,
+     * retry without rereading the relevant data or considering the semantics of the operation.
+     * <p>
+     * For more information on how transactions affect retries,
+     * see the documentation of the {@value #TRANSIENT_TRANSACTION_ERROR_LABEL}, {@value #UNKNOWN_TRANSACTION_COMMIT_RESULT_LABEL}
+     * error labels.
      *
      * @see #hasErrorLabel(String)
+     * @see MongoClientSettings.Builder#retryWrites(boolean)
+     * @see MongoClientSettings.Builder#retryReads(boolean)
+     * @mongodb.atlas.manual overload-errors/ Overload errors
      * @since 5.7
      * @mongodb.server.release 8.3
      */
-    // TODO-BACKPRESSURE Valentin Add a @mongodb.driver.manual link or something similar, see `content/atlas/source/overload-errors.txt` in https://github.com/10gen/docs-mongodb-internal/pull/17281
     public static final String RETRYABLE_ERROR_LABEL = "RetryableError";
 
     private static final long serialVersionUID = -4415279469780082174L;
diff --git a/driver-core/src/test/unit/com/mongodb/AbstractConnectionStringTest.java b/driver-core/src/test/unit/com/mongodb/AbstractConnectionStringTest.java
index d511d2750eb..8aa0b7d5a9e 100644
--- a/driver-core/src/test/unit/com/mongodb/AbstractConnectionStringTest.java
+++ b/driver-core/src/test/unit/com/mongodb/AbstractConnectionStringTest.java
@@ -122,6 +122,9 @@ protected void testValidOptions() {
             } else if (option.getKey().equalsIgnoreCase("retrywrites")) {
                 boolean expected = option.getValue().asBoolean().getValue();
                 assertEquals(expected, connectionString.getRetryWritesValue().booleanValue());
+            } else if (option.getKey().equalsIgnoreCase("maxadaptiveretries")) {
+                int expected = option.getValue().asInt32().getValue();
+                assertEquals(expected, connectionString.getMaxAdaptiveRetries().intValue());
             } else if (option.getKey().equalsIgnoreCase("replicaset")) {
                 String expected = option.getValue().asString().getValue();
                 assertEquals(expected, connectionString.getRequiredReplicaSetName());
diff --git a/driver-core/src/test/unit/com/mongodb/ConnectionStringUnitTest.java b/driver-core/src/test/unit/com/mongodb/ConnectionStringUnitTest.java
index 0b3dd1a0814..c40ea5a0ab6 100644
--- a/driver-core/src/test/unit/com/mongodb/ConnectionStringUnitTest.java
+++ b/driver-core/src/test/unit/com/mongodb/ConnectionStringUnitTest.java
@@ -37,7 +37,30 @@ final class ConnectionStringUnitTest {
     @Test
     void defaults() {
         ConnectionString connectionStringDefault = new ConnectionString(DEFAULT_OPTIONS);
-        assertAll(() -> assertNull(connectionStringDefault.getServerMonitoringMode()));
+        assertAll(
+                () -> assertNull(connectionStringDefault.getServerMonitoringMode()),
+                () -> assertNull(connectionStringDefault.getMaxAdaptiveRetries())
+        );
+    }
+
+    @ParameterizedTest
+    @ValueSource(strings = {
+            "serverMonitoringMode=stream",
+            "maxAdaptiveRetries=42"
+    })
+    void equalAndHashCode(final String connectionStringOptions) {
+        ConnectionString default1 = new ConnectionString(DEFAULT_OPTIONS);
+        ConnectionString default2 = new ConnectionString(DEFAULT_OPTIONS);
+        String connectionString = DEFAULT_OPTIONS + connectionStringOptions;
+        ConnectionString actual1 = new ConnectionString(connectionString);
+        ConnectionString actual2 = new ConnectionString(connectionString);
+        assertAll(
+                () -> assertEquals(default1, default2),
+                () -> assertEquals(default1.hashCode(), default2.hashCode()),
+                () -> assertEquals(actual1, actual2),
+                () -> assertEquals(actual1.hashCode(), actual2.hashCode()),
+                () -> assertNotEquals(default1, actual1)
+        );
     }
 
     @Test
@@ -68,22 +91,6 @@ private static String encode(final String string) {
         }
     }
 
-    @ParameterizedTest
-    @ValueSource(strings = {DEFAULT_OPTIONS + "serverMonitoringMode=stream"})
-    void equalAndHashCode(final String connectionString) {
-        ConnectionString default1 = new ConnectionString(DEFAULT_OPTIONS);
-        ConnectionString default2 = new ConnectionString(DEFAULT_OPTIONS);
-        ConnectionString actual1 = new ConnectionString(connectionString);
-        ConnectionString actual2 = new ConnectionString(connectionString);
-        assertAll(
-                () -> assertEquals(default1, default2),
-                () -> assertEquals(default1.hashCode(), default2.hashCode()),
-                () -> assertEquals(actual1, actual2),
-                () -> assertEquals(actual1.hashCode(), actual2.hashCode()),
-                () -> assertNotEquals(default1, actual1)
-        );
-    }
-
     @Test
     void serverMonitoringMode() {
         assertAll(
@@ -94,7 +101,6 @@ void serverMonitoringMode() {
         );
     }
 
-
     @ParameterizedTest
     @ValueSource(strings = {"mongodb://foo:bar/@hostname/java?", "mongodb://foo:bar?@hostname/java/",
                             "mongodb+srv://foo:bar/@hostname/java?", "mongodb+srv://foo:bar?@hostname/java/",
@@ -109,4 +115,18 @@ void unescapedPasswordsShouldNotBeLeakedInExceptionMessages(final String input)
         assertFalse(exception.getMessage().contains("bar"));
         assertFalse(exception.getMessage().contains("12345678"));
     }
+
+    @Test
+    void maxAdaptiveRetries() {
+        assertAll(
+                () -> assertEquals(42,
+                        new ConnectionString(DEFAULT_OPTIONS + "maxAdaptiveRetries=42").getMaxAdaptiveRetries()),
+                () -> assertEquals(0,
+                        new ConnectionString(DEFAULT_OPTIONS + "maxAdaptiveRetries=0").getMaxAdaptiveRetries()),
+                () -> assertThrows(IllegalArgumentException.class,
+                        () -> new ConnectionString(DEFAULT_OPTIONS + "maxAdaptiveRetries=-1")),
+                () -> assertThrows(IllegalArgumentException.class,
+                        () -> new ConnectionString(DEFAULT_OPTIONS + "maxAdaptiveRetries=invalid"))
+        );
+    }
 }
diff --git a/driver-core/src/test/unit/com/mongodb/MongoClientSettingsSpecification.groovy b/driver-core/src/test/unit/com/mongodb/MongoClientSettingsSpecification.groovy
index c8910751552..d4b59f0cb52 100644
--- a/driver-core/src/test/unit/com/mongodb/MongoClientSettingsSpecification.groovy
+++ b/driver-core/src/test/unit/com/mongodb/MongoClientSettingsSpecification.groovy
@@ -46,6 +46,7 @@ class MongoClientSettingsSpecification extends Specification {
         settings.getWriteConcern() == WriteConcern.ACKNOWLEDGED
         settings.getRetryWrites()
         settings.getRetryReads()
+        settings.getMaxAdaptiveRetries() == null
         settings.getReadConcern() == ReadConcern.DEFAULT
         settings.getReadPreference() == ReadPreference.primary()
         settings.getCommandListeners().isEmpty()
@@ -82,6 +83,11 @@ class MongoClientSettingsSpecification extends Specification {
         then:
         thrown(IllegalArgumentException)
 
+        when:
+        builder.maxAdaptiveRetries(-1)
+        then:
+        thrown(IllegalArgumentException)
+
         when:
         builder.credential(null)
         then:
@@ -135,6 +141,7 @@ class MongoClientSettingsSpecification extends Specification {
                 .writeConcern(WriteConcern.JOURNALED)
                 .retryWrites(true)
                 .retryReads(true)
+                .maxAdaptiveRetries(42)
                 .readConcern(ReadConcern.LOCAL)
                 .applicationName('app1')
                 .addCommandListener(commandListener)
@@ -160,6 +167,7 @@ class MongoClientSettingsSpecification extends Specification {
         settings.getWriteConcern() == WriteConcern.JOURNALED
         settings.getRetryWrites()
         settings.getRetryReads()
+        settings.getMaxAdaptiveRetries() == 42
         settings.getReadConcern() == ReadConcern.LOCAL
         settings.getApplicationName() == 'app1'
         settings.getSocketSettings() == SocketSettings.builder().build()
@@ -200,6 +208,7 @@ class MongoClientSettingsSpecification extends Specification {
                 .writeConcern(WriteConcern.JOURNALED)
                 .retryWrites(true)
                 .retryReads(true)
+                .maxAdaptiveRetries(42)
                 .readConcern(ReadConcern.LOCAL)
                 .applicationName('app1')
                 .addCommandListener(commandListener)
@@ -330,6 +339,7 @@ class MongoClientSettingsSpecification extends Specification {
                 + '&replicaSet=test'
                 + '&retryWrites=true'
                 + '&retryReads=true'
+                + '&maxAdaptiveRetries=42'
                 + '&ssl=true&sslInvalidHostNameAllowed=true'
                 + '&w=majority&wTimeoutMS=2500'
                 + '&readPreference=secondary'
@@ -398,6 +408,7 @@ class MongoClientSettingsSpecification extends Specification {
             .compressorList([MongoCompressor.createZlibCompressor().withProperty(MongoCompressor.LEVEL, 5)])
             .retryWrites(true)
             .retryReads(true)
+            .maxAdaptiveRetries(42)
             .uuidRepresentation(UuidRepresentation.STANDARD)
             .timeout(10000, TimeUnit.MILLISECONDS)
             .build()
@@ -462,6 +473,7 @@ class MongoClientSettingsSpecification extends Specification {
                 .compressorList([MongoCompressor.createZlibCompressor().withProperty(MongoCompressor.LEVEL, 5)])
                 .retryWrites(true)
                 .retryReads(true)
+                .maxAdaptiveRetries(null)
 
         def expectedSettings = builder.build()
         def settingsWithDefaultConnectionStringApplied = builder
@@ -546,6 +558,18 @@ class MongoClientSettingsSpecification extends Specification {
                 .build()
     }
 
+    def 'should allow null, 0 maxAdaptiveRetries'() {
+        when:
+        def settings = MongoClientSettings.builder().maxAdaptiveRetries(null).build()
+        then:
+        settings.getMaxAdaptiveRetries() == null
+
+        when:
+        settings = MongoClientSettings.builder().maxAdaptiveRetries(0).build()
+        then:
+        settings.getMaxAdaptiveRetries() == 0
+    }
+
     def 'should only have the following fields in the builder'() {
         when:
         // A regression test so that if anymore fields are added then the builder(final MongoClientSettings settings) should be updated
@@ -553,7 +577,7 @@ class MongoClientSettingsSpecification extends Specification {
         def expected = ['applicationName', 'autoEncryptionSettings', 'clusterSettingsBuilder', 'codecRegistry', 'commandListeners',
                         'compressorList', 'connectionPoolSettingsBuilder', 'contextProvider', 'credential', 'dnsClient',
                         'heartbeatConnectTimeoutMS', 'heartbeatSocketTimeoutMS', 'inetAddressResolver', 'loggerSettingsBuilder',
-                        'observabilitySettings',
+                        'maxAdaptiveRetries', 'observabilitySettings',
                         'readConcern', 'readPreference', 'retryReads',
                         'retryWrites', 'serverApi', 'serverSettingsBuilder', 'socketSettingsBuilder', 'sslSettingsBuilder',
                         'timeoutMS', 'transportSettings', 'uuidRepresentation',
@@ -572,7 +596,7 @@ class MongoClientSettingsSpecification extends Specification {
                         'applyToSslSettings', 'autoEncryptionSettings', 'build', 'codecRegistry', 'commandListenerList',
                         'compressorList', 'contextProvider', 'credential', 'dnsClient',
                         'heartbeatConnectTimeoutMS',
-                        'heartbeatSocketTimeoutMS', 'inetAddressResolver', 'observabilitySettings', 'readConcern',
+                        'heartbeatSocketTimeoutMS', 'inetAddressResolver', 'maxAdaptiveRetries', 'observabilitySettings', 'readConcern',
                         'readPreference',
                         'retryReads', 'retryWrites',
                         'serverApi', 'timeout', 'transportSettings',
diff --git a/driver-kotlin-coroutine/src/main/kotlin/com/mongodb/kotlin/client/coroutine/ClientSession.kt b/driver-kotlin-coroutine/src/main/kotlin/com/mongodb/kotlin/client/coroutine/ClientSession.kt
index 6c53a1faf47..f5bb4d742c1 100644
--- a/driver-kotlin-coroutine/src/main/kotlin/com/mongodb/kotlin/client/coroutine/ClientSession.kt
+++ b/driver-kotlin-coroutine/src/main/kotlin/com/mongodb/kotlin/client/coroutine/ClientSession.kt
@@ -184,6 +184,8 @@ public class ClientSession(public val wrapped: reactiveClientSession) : jClientS
     /**
      * Start a transaction in the context of this session with default transaction options. A transaction can not be
      * started if there is already an active transaction on this session.
+     *
+     * @see com.mongodb.MongoException.TRANSIENT_TRANSACTION_ERROR_LABEL
      */
     public fun startTransaction(): Unit = wrapped.startTransaction()
 
@@ -192,6 +194,7 @@ public class ClientSession(public val wrapped: reactiveClientSession) : jClientS
      * started if there is already an active transaction on this session.
      *
      * @param transactionOptions the options to apply to the transaction
+     * @see com.mongodb.MongoException.TRANSIENT_TRANSACTION_ERROR_LABEL
      */
     public fun startTransaction(transactionOptions: TransactionOptions): Unit =
         wrapped.startTransaction(transactionOptions)
@@ -201,6 +204,7 @@ public class ClientSession(public val wrapped: reactiveClientSession) : jClientS
      * started.
      *
      * @return an empty publisher that indicates when the operation has completed
+     * @see com.mongodb.MongoException.UNKNOWN_TRANSACTION_COMMIT_RESULT_LABEL
      */
     public suspend fun commitTransaction() {
         wrapped.commitTransaction().awaitFirstOrNull()
diff --git a/driver-kotlin-sync/src/main/kotlin/com/mongodb/kotlin/client/ClientSession.kt b/driver-kotlin-sync/src/main/kotlin/com/mongodb/kotlin/client/ClientSession.kt
index 5656feb4523..6a9ddc243b8 100644
--- a/driver-kotlin-sync/src/main/kotlin/com/mongodb/kotlin/client/ClientSession.kt
+++ b/driver-kotlin-sync/src/main/kotlin/com/mongodb/kotlin/client/ClientSession.kt
@@ -50,6 +50,8 @@ public class ClientSession(public val wrapped: JClientSession) : Closeable {
     /**
      * Start a transaction in the context of this session with default transaction options. A transaction can not be
      * started if there is already an active transaction on this session.
+     *
+     * @see com.mongodb.MongoException.TRANSIENT_TRANSACTION_ERROR_LABEL
      */
     public fun startTransaction(): Unit = wrapped.startTransaction()
 
@@ -58,6 +60,7 @@ public class ClientSession(public val wrapped: JClientSession) : Closeable {
      * started if there is already an active transaction on this session.
      *
      * @param transactionOptions the options to apply to the transaction
+     * @see com.mongodb.MongoException.TRANSIENT_TRANSACTION_ERROR_LABEL
      */
     public fun startTransaction(transactionOptions: TransactionOptions): Unit =
         wrapped.startTransaction(transactionOptions)
@@ -65,6 +68,8 @@ public class ClientSession(public val wrapped: JClientSession) : Closeable {
     /**
      * Commit a transaction in the context of this session. A transaction can only be commmited if one has first been
      * started.
+     *
+     * @see com.mongodb.MongoException.UNKNOWN_TRANSACTION_COMMIT_RESULT_LABEL
      */
     public fun commitTransaction(): Unit = wrapped.commitTransaction()
 
@@ -82,6 +87,8 @@ public class ClientSession(public val wrapped: JClientSession) : Closeable {
      * @param transactionBody the body of the transaction
      * @param options the transaction options
      * @return the return value of the transaction body
+     * @see com.mongodb.MongoException.TRANSIENT_TRANSACTION_ERROR_LABEL
+     * @see com.mongodb.MongoException.UNKNOWN_TRANSACTION_COMMIT_RESULT_LABEL
      */
     public fun <T : Any> withTransaction(
         transactionBody: () -> T,
diff --git a/driver-legacy/src/main/com/mongodb/MongoClientOptions.java b/driver-legacy/src/main/com/mongodb/MongoClientOptions.java
index 1f19fba3484..fe7b827d362 100644
--- a/driver-legacy/src/main/com/mongodb/MongoClientOptions.java
+++ b/driver-legacy/src/main/com/mongodb/MongoClientOptions.java
@@ -17,6 +17,7 @@
 package com.mongodb;
 
 import com.mongodb.annotations.Alpha;
+import com.mongodb.annotations.Beta;
 import com.mongodb.annotations.Immutable;
 import com.mongodb.annotations.NotThreadSafe;
 import com.mongodb.annotations.Reason;
@@ -442,11 +443,14 @@ public WriteConcern getWriteConcern() {
     }
 
     /**
-     * Returns true if writes should be retried if they fail due to a network error or other retryable error.
+     * Returns whether attempts to execute write commands should be retried if they fail due to a retryable error.
+     * See {@link MongoClientSettings.Builder#retryWrites(boolean)} for more information.
      *
      * <p>Starting with the 3.11.0 release, the default value is true</p>
      *
      * @return the retryWrites value
+     * @see Builder#retryWrites(boolean)
+     * @see #getMaxAdaptiveRetries()
      * @mongodb.server.release 3.6
      * @since 3.6
      */
@@ -455,9 +459,14 @@ public boolean getRetryWrites() {
     }
 
     /**
-     * Returns true if reads should be retried if they fail due to a network error or other retryable error.
+     * Returns whether attempts to execute read commands should be retried if they fail due to a retryable error.
+     * See {@link MongoClientSettings.Builder#retryReads(boolean)} for more information.
+     * <p>
+     * Default is {@code true}.
      *
      * @return the retryReads value
+     * @see Builder#retryReads(boolean)
+     * @see #getMaxAdaptiveRetries()
      * @mongodb.server.release 3.6
      * @since 3.11
      */
@@ -465,6 +474,20 @@ public boolean getRetryReads() {
         return wrapped.getRetryReads();
     }
 
+    /**
+     * Returns the maximum number of retry attempts when encountering a retryable overload error.
+     * See {@link MongoClientSettings.Builder#maxAdaptiveRetries(Integer)} for more information.
+     *
+     * @return The maximum number of retry attempts when encountering a retryable overload error.
+     * @see Builder#maxAdaptiveRetries(Integer)
+     * @since 5.7
+     */
+    @Beta(Reason.CLIENT)
+    @Nullable
+    public Integer getMaxAdaptiveRetries() {
+        return wrapped.getMaxAdaptiveRetries();
+    }
+
     /**
      * <p>The read concern to use.</p>
      *
@@ -1020,14 +1043,16 @@ public Builder writeConcern(final WriteConcern writeConcern) {
         }
 
         /**
-         * Sets whether writes should be retried if they fail due to a network error.
+         * Sets whether attempts to execute write commands should be retried if they fail due to a retryable error.
+         * See {@link MongoClientSettings.Builder#retryWrites(boolean)} for more information.
          *
          * <p>Starting with the 3.11.0 release, the default value is true</p>
          *
-         * @param retryWrites sets if writes should be retried if they fail due to a network error.
+         * @param retryWrites sets if write commands should be retried if they fail due to a retryable error.
          * @return {@code this}
          * @mongodb.server.release 3.6
          * @see #getRetryWrites()
+         * @see #maxAdaptiveRetries(Integer)
          * @since 3.6
          */
         public Builder retryWrites(final boolean retryWrites) {
@@ -1036,12 +1061,16 @@ public Builder retryWrites(final boolean retryWrites) {
         }
 
         /**
-         * Sets whether reads should be retried if they fail due to a network error.
+         * Sets whether attempts to execute read commands should be retried if they fail due to a retryable error.
+         * See {@link MongoClientSettings.Builder#retryReads(boolean)} for more information.
+         * <p>
+         * Default is {@code true}.
          *
-         * @param retryReads sets if reads should be retried if they fail due to a network error.
+         * @param retryReads sets if read commands should be retried if they fail due to a retryable error.
          * @return {@code this}
          * @mongodb.server.release 3.6
          * @see #getRetryReads()
+         * @see #maxAdaptiveRetries(Integer)
          * @since 3.11
          */
         public Builder retryReads(final boolean retryReads) {
@@ -1049,6 +1078,21 @@ public Builder retryReads(final boolean retryReads) {
             return this;
         }
 
+        /**
+         * Sets the maximum number of retry attempts when encountering a retryable overload error.
+         * See {@link MongoClientSettings.Builder#maxAdaptiveRetries(Integer)} for more information.
+         *
+         * @param maxAdaptiveRetries Sets the maximum number of retry attempts when encountering a retryable overload error.
+         * @return {@code this}.
+         * @see #getMaxAdaptiveRetries()
+         * @since 5.7
+         */
+        @Beta(Reason.CLIENT)
+        public Builder maxAdaptiveRetries(@Nullable final Integer maxAdaptiveRetries) {
+            wrapped.maxAdaptiveRetries(maxAdaptiveRetries);
+            return this;
+        }
+
         /**
          * Sets the read concern.
          *
diff --git a/driver-legacy/src/main/com/mongodb/MongoClientURI.java b/driver-legacy/src/main/com/mongodb/MongoClientURI.java
index e471bbf1686..5d129bbd07f 100644
--- a/driver-legacy/src/main/com/mongodb/MongoClientURI.java
+++ b/driver-legacy/src/main/com/mongodb/MongoClientURI.java
@@ -16,6 +16,7 @@
 
 package com.mongodb;
 
+import com.mongodb.annotations.Beta;
 import com.mongodb.lang.Nullable;
 import org.bson.UuidRepresentation;
 
@@ -147,10 +148,6 @@
  *          <li>Used in combination with {@code w}</li>
  *      </ul>
  *  </li>
- *  <li>{@code retryWrites=true|false}. If true the driver will retry supported write operations if they fail due to a network error.
- *  Defaults to false.</li>
- *  <li>{@code retryReads=true|false}. If true the driver will retry supported read operations if they fail due to a network error.
- *  Defaults to false.</li>
  * </ul>
  *
  *
@@ -214,10 +211,13 @@
  * </ul>
  * <p>General configuration:</p>
  * <ul>
- * <li>{@code retryWrites=true|false}. If true the driver will retry supported write operations if they fail due to a network error.
- *  Defaults to true.</li>
- * <li>{@code retryReads=true|false}. If true the driver will retry supported read operations if they fail due to a network error.
- *  Defaults to true.</li>
+ * <li>{@code retryWrites=true|false}: Whether attempts to execute write commands should be retried if they fail due to a retryable error.
+ *  Defaults to true. See also {@code maxAdaptiveRetries}.</li>
+ * <li>{@code retryReads=true|false}: Whether attempts to execute read commands should be retried if they fail due to a retryable error.
+ *  Defaults to true. See also {@code maxAdaptiveRetries}.</li>
+ * <li>{@code maxAdaptiveRetries=n}: This is {@linkplain Beta Beta API}.
+ * The maximum number of retry attempts when encountering a retryable overload error.
+ * See {@link MongoClientSettings.Builder#maxAdaptiveRetries(Integer)} for more information.</li>
  * <li>{@code uuidRepresentation=unspecified|standard|javaLegacy|csharpLegacy|pythonLegacy}.  See
  * {@link MongoClientOptions#getUuidRepresentation()} for documentation of semantics of this parameter.  Defaults to "javaLegacy", but
  * will change to "unspecified" in the next major release.</li>
@@ -381,11 +381,14 @@ public MongoClientOptions getOptions() {
         if (retryWritesValue != null) {
             builder.retryWrites(retryWritesValue);
         }
-
         Boolean retryReads = proxied.getRetryReads();
         if (retryReads != null) {
             builder.retryReads(retryReads);
         }
+        Integer maxAdaptiveRetries = proxied.getMaxAdaptiveRetries();
+        if (maxAdaptiveRetries != null) {
+            builder.maxAdaptiveRetries(maxAdaptiveRetries);
+        }
 
         Integer maxConnectionPoolSize = proxied.getMaxConnectionPoolSize();
         if (maxConnectionPoolSize != null) {
diff --git a/driver-legacy/src/test/unit/com/mongodb/MongoClientOptionsSpecification.groovy b/driver-legacy/src/test/unit/com/mongodb/MongoClientOptionsSpecification.groovy
index ae1d332674c..723dddcc280 100644
--- a/driver-legacy/src/test/unit/com/mongodb/MongoClientOptionsSpecification.groovy
+++ b/driver-legacy/src/test/unit/com/mongodb/MongoClientOptionsSpecification.groovy
@@ -46,6 +46,7 @@ class MongoClientOptionsSpecification extends Specification {
         options.getWriteConcern() == WriteConcern.ACKNOWLEDGED
         options.getRetryWrites()
         options.getRetryReads()
+        options.getMaxAdaptiveRetries() == null
         options.getCodecRegistry() == MongoClientSettings.defaultCodecRegistry
         options.getUuidRepresentation() == UuidRepresentation.UNSPECIFIED
         options.getMinConnectionsPerHost() == 0
@@ -84,6 +85,11 @@ class MongoClientOptionsSpecification extends Specification {
         given:
         def builder = new MongoClientOptions.Builder()
 
+        when:
+        builder.maxAdaptiveRetries(-1)
+        then:
+        thrown(IllegalArgumentException)
+
         when:
         builder.dbDecoderFactory(null)
         then:
@@ -116,6 +122,7 @@ class MongoClientOptionsSpecification extends Specification {
                                         .readPreference(ReadPreference.secondary())
                                         .retryWrites(true)
                                         .retryReads(false)
+                                        .maxAdaptiveRetries(42)
                                         .writeConcern(WriteConcern.JOURNALED)
                                         .readConcern(ReadConcern.MAJORITY)
                                         .minConnectionsPerHost(30)
@@ -162,6 +169,7 @@ class MongoClientOptionsSpecification extends Specification {
         options.getServerSelector() == serverSelector
         options.getRetryWrites()
         !options.getRetryReads()
+        options.getMaxAdaptiveRetries() == 42
         options.getServerSelectionTimeout() == 150
         options.getTimeout() == 10_000
         options.getMaxWaitTime() == 200
@@ -207,6 +215,7 @@ class MongoClientOptionsSpecification extends Specification {
         settings.writeConcern == WriteConcern.JOURNALED
         settings.retryWrites
         !settings.retryReads
+        settings.getMaxAdaptiveRetries() == 42
         settings.autoEncryptionSettings == autoEncryptionSettings
         settings.codecRegistry == codecRegistry
         settings.commandListeners == [commandListener]
@@ -227,6 +236,7 @@ class MongoClientOptionsSpecification extends Specification {
         optionsFromSettings.getServerSelector() == serverSelector
         optionsFromSettings.getRetryWrites()
         !optionsFromSettings.getRetryReads()
+        optionsFromSettings.getMaxAdaptiveRetries() == 42
         optionsFromSettings.getServerSelectionTimeout() == 150
         optionsFromSettings.getServerSelectionTimeout() == 150
         optionsFromSettings.getMaxWaitTime() == 200
@@ -619,6 +629,7 @@ class MongoClientOptionsSpecification extends Specification {
                 .writeConcern(WriteConcern.JOURNALED)
                 .retryWrites(true)
                 .retryReads(true)
+                .maxAdaptiveRetries(42)
                 .uuidRepresentation(UuidRepresentation.STANDARD)
                 .minConnectionsPerHost(30)
                 .connectionsPerHost(500)
@@ -663,6 +674,18 @@ class MongoClientOptionsSpecification extends Specification {
         MongoClientOptions.builder().connectionsPerHost(0).build().getConnectionsPerHost() == 0
     }
 
+    def 'should allow null, 0 maxAdaptiveRetries'() {
+        when:
+        def options = MongoClientOptions.builder().maxAdaptiveRetries(null).build()
+        then:
+        options.getMaxAdaptiveRetries() == null
+
+        when:
+        options = MongoClientOptions.builder().maxAdaptiveRetries(0).build()
+        then:
+        options.getMaxAdaptiveRetries() == 0
+    }
+
     private static class MyDBEncoderFactory implements DBEncoderFactory {
         @Override
         DBEncoder create() {
diff --git a/driver-legacy/src/test/unit/com/mongodb/MongoClientURISpecification.groovy b/driver-legacy/src/test/unit/com/mongodb/MongoClientURISpecification.groovy
index 241ac958c8a..fb2509554a4 100644
--- a/driver-legacy/src/test/unit/com/mongodb/MongoClientURISpecification.groovy
+++ b/driver-legacy/src/test/unit/com/mongodb/MongoClientURISpecification.groovy
@@ -131,6 +131,7 @@ class MongoClientURISpecification extends Specification {
                 + 'heartbeatFrequencyMS=20000&'
                 + 'retryWrites=true&'
                 + 'retryReads=true&'
+                + 'maxAdaptiveRetries=42&'
                 + 'uuidRepresentation=csharpLegacy&'
                 + 'appName=app1&'
                 + 'timeoutMS=10000')
@@ -158,6 +159,7 @@ class MongoClientURISpecification extends Specification {
         options.getHeartbeatFrequency() == 20000
         options.getRetryWrites()
         options.getRetryReads()
+        options.getMaxAdaptiveRetries() == 42
         options.getUuidRepresentation() == UuidRepresentation.C_SHARP_LEGACY
         options.getApplicationName() == 'app1'
     }
@@ -178,6 +180,7 @@ class MongoClientURISpecification extends Specification {
         !options.isSslEnabled()
         options.getRetryWrites()
         options.getRetryReads()
+        options.getMaxAdaptiveRetries() == null
         options.getUuidRepresentation() == UuidRepresentation.UNSPECIFIED
     }
 
@@ -188,6 +191,7 @@ class MongoClientURISpecification extends Specification {
                 .readPreference(ReadPreference.secondary())
                 .retryWrites(true)
                 .retryReads(true)
+                .maxAdaptiveRetries(42)
                 .writeConcern(WriteConcern.JOURNALED)
                 .minConnectionsPerHost(30)
                 .connectionsPerHost(500)
@@ -220,6 +224,7 @@ class MongoClientURISpecification extends Specification {
         options.getWriteConcern() == WriteConcern.JOURNALED
         options.getRetryWrites()
         options.getRetryReads()
+        options.getMaxAdaptiveRetries() == 42
         options.getTimeout() == 10_000
         options.getServerSelectionTimeout() == 150
         options.getMaxWaitTime() == 200
@@ -314,24 +319,33 @@ class MongoClientURISpecification extends Specification {
 
     def 'should respect MongoClientOptions builder'() {
         given:
-        def uri = new MongoClientURI('mongodb://localhost/', MongoClientOptions.builder().connectionsPerHost(200))
+        def uri = new MongoClientURI('mongodb://localhost/', MongoClientOptions.builder()
+                .connectionsPerHost(200)
+                .maxAdaptiveRetries(42))
 
         when:
         def options = uri.getOptions()
 
         then:
         options.getConnectionsPerHost() == 200
+        options.getMaxAdaptiveRetries() == 42
     }
 
     def 'should override MongoClientOptions builder'() {
         given:
-        def uri = new MongoClientURI('mongodb://localhost/?maxPoolSize=250', MongoClientOptions.builder().connectionsPerHost(200))
+        def uri = new MongoClientURI('mongodb://localhost/?'
+                + 'maxPoolSize=250'
+                + '&maxAdaptiveRetries=43',
+                MongoClientOptions.builder().
+                        connectionsPerHost(200)
+                        .maxAdaptiveRetries(42))
 
         when:
         def options = uri.getOptions()
 
         then:
         options.getConnectionsPerHost() == 250
+        options.getMaxAdaptiveRetries() == 43
     }
 
     def 'should be equal to another MongoClientURI with the same string values'() {
@@ -371,7 +385,9 @@ class MongoClientURISpecification extends Specification {
                          + 'socketTimeoutMS=5500;'
                          + 'safe=false;w=1;wtimeout=2500;'
                          + 'fsync=true;readPreference=primary;'
-                         + 'ssl=true')                               |  new MongoClientURI('mongodb://localhost/db.coll?minPoolSize=5;'
+                         + 'ssl=true;'
+                         + 'maxAdaptiveRetries=42')                 |  new MongoClientURI('mongodb://localhost/db.coll?'
+                                                                                         + 'minPoolSize=5;'
                                                                                          + 'maxPoolSize=10;'
                                                                                          + 'waitQueueTimeoutMS=150;'
                                                                                          + 'maxIdleTimeMS=200&maxLifeTimeMS=300;'
@@ -379,7 +395,8 @@ class MongoClientURISpecification extends Specification {
                                                                                          + '&replicaSet=test;connectTimeoutMS=2500;'
                                                                                          + 'socketTimeoutMS=5500&safe=false&w=1;'
                                                                                          + 'wtimeout=2500;fsync=true'
-                                                                                         + '&readPreference=primary;ssl=true')
+                                                                                         + '&readPreference=primary;ssl=true;'
+                                                                                         + 'maxAdaptiveRetries=42')
     }
 
     def 'should be not equal to another MongoClientURI with the different string values'() {
@@ -401,12 +418,14 @@ class MongoClientURISpecification extends Specification {
                          + '&readPreferenceTags=dc:ny,rack:1'
                          + '&readPreferenceTags=dc:ny'
                          + '&readPreferenceTags='
-                         + '&maxConnecting=1')                  | new MongoClientURI('mongodb://localhost/'
+                         + '&maxConnecting=1'
+                         + '&maxAdaptiveRetries=42')                 | new MongoClientURI('mongodb://localhost/'
                                                                                        + '?readPreference=secondaryPreferred'
                                                                                        + '&readPreferenceTags=dc:ny'
                                                                                        + '&readPreferenceTags=dc:ny, rack:1'
                                                                                        + '&readPreferenceTags='
-                                                                                       + '&maxConnecting=2')
+                                                                                       + '&maxConnecting=2'
+                                                                                       + '&maxAdaptiveRetries=43')
         new MongoClientURI('mongodb://ross:123@localhost/?'
                          + 'authMechanism=SCRAM-SHA-1')            | new MongoClientURI('mongodb://ross:123@localhost/?'
                                                                                        + 'authMechanism=GSSAPI')
@@ -419,7 +438,8 @@ class MongoClientURISpecification extends Specification {
                                                         + 'minPoolSize=7;maxIdleTimeMS=1000;maxLifeTimeMS=2000;maxConnecting=1;'
                                                         + 'replicaSet=test;'
                                                         + 'connectTimeoutMS=2500;socketTimeoutMS=5500;autoConnectRetry=true;'
-                                                        + 'readPreference=secondaryPreferred;safe=false;w=1;wtimeout=2600')
+                                                        + 'readPreference=secondaryPreferred;safe=false;w=1;wtimeout=2600;'
+                                                        + 'maxAdaptiveRetries=42')
 
         MongoClientOptions.Builder builder = MongoClientOptions.builder()
                                                                .connectionsPerHost(10)
@@ -433,6 +453,7 @@ class MongoClientURISpecification extends Specification {
                                                                .socketTimeout(5500)
                                                                .readPreference(secondaryPreferred())
                                                                .writeConcern(new WriteConcern(1, 2600))
+                                                               .maxAdaptiveRetries(42)
 
         MongoClientOptions options = builder.build()
 
diff --git a/driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/ClientSession.java b/driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/ClientSession.java
index 3d9354e9ae9..400728a3b29 100644
--- a/driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/ClientSession.java
+++ b/driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/ClientSession.java
@@ -17,6 +17,7 @@
 
 package com.mongodb.reactivestreams.client;
 
+import com.mongodb.MongoException;
 import com.mongodb.TransactionOptions;
 import org.reactivestreams.Publisher;
 
@@ -65,6 +66,7 @@ public interface ClientSession extends com.mongodb.session.ClientSession {
      * Start a transaction in the context of this session with default transaction options. A transaction can not be started if there is
      * already an active transaction on this session.
      *
+     * @see MongoException#TRANSIENT_TRANSACTION_ERROR_LABEL
      * @mongodb.server.release 4.0
      */
     void startTransaction();
@@ -75,6 +77,7 @@ public interface ClientSession extends com.mongodb.session.ClientSession {
      *
      * @param transactionOptions the options to apply to the transaction
      *
+     * @see MongoException#TRANSIENT_TRANSACTION_ERROR_LABEL
      * @mongodb.server.release 4.0
      */
     void startTransaction(TransactionOptions transactionOptions);
@@ -83,6 +86,7 @@ public interface ClientSession extends com.mongodb.session.ClientSession {
      * Commit a transaction in the context of this session.  A transaction can only be commmited if one has first been started.
      *
      * @return an empty publisher that indicates when the operation has completed
+     * @see MongoException#UNKNOWN_TRANSACTION_COMMIT_RESULT_LABEL
      * @mongodb.server.release 4.0
      */
     Publisher<Void> commitTransaction();
diff --git a/driver-scala/src/main/scala/org/mongodb/scala/package.scala b/driver-scala/src/main/scala/org/mongodb/scala/package.scala
index 1cdc2d0a564..487987a6fe9 100644
--- a/driver-scala/src/main/scala/org/mongodb/scala/package.scala
+++ b/driver-scala/src/main/scala/org/mongodb/scala/package.scala
@@ -215,18 +215,48 @@ package object scala extends ClientSessionImplicits with ObservableImplicits wit
 
     /**
      * An error label indicating that the exception can be treated as a transient transaction error.
+     * See the documentation linked below for more information.
      *
+     * @see [[https://www.mongodb.com/docs/manual/core/transactions-in-applications/#std-label-transient-transaction-error TransientTransactionError]]
      * @since 2.4
      */
     val TRANSIENT_TRANSACTION_ERROR_LABEL: String = com.mongodb.MongoException.TRANSIENT_TRANSACTION_ERROR_LABEL
 
     /**
      * An error label indicating that the exception can be treated as an unknown transaction commit result.
+     * See the documentation linked below for more information.
      *
+     * @see [[https://www.mongodb.com/docs/manual/core/transactions-in-applications/#std-label-unknown-transaction-commit-result UnknownTransactionCommitResult]]
      * @since 2.4
      */
     val UNKNOWN_TRANSACTION_COMMIT_RESULT_LABEL: String =
       com.mongodb.MongoException.UNKNOWN_TRANSACTION_COMMIT_RESULT_LABEL
+
+    /**
+     * Server is overloaded and shedding load.
+     * If an application retries explicitly, it should use exponential backoff because the server has indicated overload.
+     * This label on its own does not mean that the operation can be [[MongoException.RETRYABLE_ERROR_LABEL safely retried]].
+     *
+     * @see [[https://www.mongodb.com/docs/atlas/overload-errors/ Overload errors]]
+     * @since 5.7
+     * @note Requires MongoDB 8.3 or greater
+     */
+    val SYSTEM_OVERLOADED_ERROR_LABEL: String = com.mongodb.MongoException.SYSTEM_OVERLOADED_ERROR_LABEL
+
+    /**
+     * The operation is safe to retry, that is,
+     * retry without rereading the relevant data or considering the semantics of the operation.
+     *
+     * For more information on how transactions affect retries,
+     * see the documentation of the
+     * [[MongoException.TRANSIENT_TRANSACTION_ERROR_LABEL "TransientTransactionError"]],
+     * [[MongoException.UNKNOWN_TRANSACTION_COMMIT_RESULT_LABEL "UnknownTransactionCommitResult"]] error labels.
+     *
+     * @see [[https://www.mongodb.com/docs/atlas/overload-errors/ Overload errors]]
+     * @since 5.7
+     * @note Requires MongoDB 8.3 or greater
+     */
+    val RETRYABLE_ERROR_LABEL: String = com.mongodb.MongoException.RETRYABLE_ERROR_LABEL
   }
 
   /**
diff --git a/driver-sync/src/main/com/mongodb/client/ClientSession.java b/driver-sync/src/main/com/mongodb/client/ClientSession.java
index 00ba5eba23c..c095bdb0a40 100644
--- a/driver-sync/src/main/com/mongodb/client/ClientSession.java
+++ b/driver-sync/src/main/com/mongodb/client/ClientSession.java
@@ -16,6 +16,7 @@
 
 package com.mongodb.client;
 
+import com.mongodb.MongoException;
 import com.mongodb.ServerAddress;
 import com.mongodb.TransactionOptions;
 import com.mongodb.internal.observability.micrometer.TransactionSpan;
@@ -76,6 +77,7 @@ public interface ClientSession extends com.mongodb.session.ClientSession {
      * Start a transaction in the context of this session with default transaction options. A transaction can not be started if there is
      * already an active transaction on this session.
      *
+     * @see MongoException#TRANSIENT_TRANSACTION_ERROR_LABEL
      * @mongodb.server.release 4.0
      */
     void startTransaction();
@@ -86,6 +88,7 @@ public interface ClientSession extends com.mongodb.session.ClientSession {
      *
      * @param transactionOptions the options to apply to the transaction
      *
+     * @see MongoException#TRANSIENT_TRANSACTION_ERROR_LABEL
      * @mongodb.server.release 4.0
      */
     void startTransaction(TransactionOptions transactionOptions);
@@ -93,6 +96,7 @@ public interface ClientSession extends com.mongodb.session.ClientSession {
     /**
      * Commit a transaction in the context of this session.  A transaction can only be commmited if one has first been started.
      *
+     * @see MongoException#UNKNOWN_TRANSACTION_COMMIT_RESULT_LABEL
      * @mongodb.server.release 4.0
      */
     void commitTransaction();
@@ -110,6 +114,8 @@ public interface ClientSession extends com.mongodb.session.ClientSession {
      * @param <T> the return type of the transaction body
      * @param transactionBody the body of the transaction
      * @return the return value of the transaction body
+     * @see MongoException#TRANSIENT_TRANSACTION_ERROR_LABEL
+     * @see MongoException#UNKNOWN_TRANSACTION_COMMIT_RESULT_LABEL
      * @mongodb.server.release 4.0
      * @since 3.11
      */
@@ -122,6 +128,8 @@ public interface ClientSession extends com.mongodb.session.ClientSession {
      * @param transactionBody the body of the transaction
      * @param options         the transaction options
      * @return the return value of the transaction body
+     * @see MongoException#TRANSIENT_TRANSACTION_ERROR_LABEL
+     * @see MongoException#UNKNOWN_TRANSACTION_COMMIT_RESULT_LABEL
      * @mongodb.server.release 4.0
      * @since 3.11
      */

From b57be44d91b14a3b5658f8e8a377da72d173776f Mon Sep 17 00:00:00 2001
From: Valentin Kovalenko <valentin.kovalenko@mongodb.com>
Date: Fri, 17 Apr 2026 17:00:30 -0600
Subject: [PATCH 2/3] Fix typos in the pre-existing code

---
 .../kotlin/com/mongodb/kotlin/client/coroutine/ClientSession.kt | 2 +-
 .../src/main/kotlin/com/mongodb/kotlin/client/ClientSession.kt  | 2 +-
 .../main/com/mongodb/reactivestreams/client/ClientSession.java  | 2 +-
 .../main/scala/org/mongodb/scala/ClientSessionImplicits.scala   | 2 +-
 driver-sync/src/main/com/mongodb/client/ClientSession.java      | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/driver-kotlin-coroutine/src/main/kotlin/com/mongodb/kotlin/client/coroutine/ClientSession.kt b/driver-kotlin-coroutine/src/main/kotlin/com/mongodb/kotlin/client/coroutine/ClientSession.kt
index f5bb4d742c1..a1192285da2 100644
--- a/driver-kotlin-coroutine/src/main/kotlin/com/mongodb/kotlin/client/coroutine/ClientSession.kt
+++ b/driver-kotlin-coroutine/src/main/kotlin/com/mongodb/kotlin/client/coroutine/ClientSession.kt
@@ -200,7 +200,7 @@ public class ClientSession(public val wrapped: reactiveClientSession) : jClientS
         wrapped.startTransaction(transactionOptions)
 
     /**
-     * Commit a transaction in the context of this session. A transaction can only be commmited if one has first been
+     * Commit a transaction in the context of this session. A transaction can only be committed if one has first been
      * started.
      *
      * @return an empty publisher that indicates when the operation has completed
diff --git a/driver-kotlin-sync/src/main/kotlin/com/mongodb/kotlin/client/ClientSession.kt b/driver-kotlin-sync/src/main/kotlin/com/mongodb/kotlin/client/ClientSession.kt
index 6a9ddc243b8..0f49d667995 100644
--- a/driver-kotlin-sync/src/main/kotlin/com/mongodb/kotlin/client/ClientSession.kt
+++ b/driver-kotlin-sync/src/main/kotlin/com/mongodb/kotlin/client/ClientSession.kt
@@ -66,7 +66,7 @@ public class ClientSession(public val wrapped: JClientSession) : Closeable {
         wrapped.startTransaction(transactionOptions)
 
     /**
-     * Commit a transaction in the context of this session. A transaction can only be commmited if one has first been
+     * Commit a transaction in the context of this session. A transaction can only be committed if one has first been
      * started.
      *
      * @see com.mongodb.MongoException.UNKNOWN_TRANSACTION_COMMIT_RESULT_LABEL
diff --git a/driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/ClientSession.java b/driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/ClientSession.java
index 400728a3b29..c7301807910 100644
--- a/driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/ClientSession.java
+++ b/driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/ClientSession.java
@@ -83,7 +83,7 @@ public interface ClientSession extends com.mongodb.session.ClientSession {
     void startTransaction(TransactionOptions transactionOptions);
 
     /**
-     * Commit a transaction in the context of this session.  A transaction can only be commmited if one has first been started.
+     * Commit a transaction in the context of this session.  A transaction can only be committed if one has first been started.
      *
      * @return an empty publisher that indicates when the operation has completed
      * @see MongoException#UNKNOWN_TRANSACTION_COMMIT_RESULT_LABEL
diff --git a/driver-scala/src/main/scala/org/mongodb/scala/ClientSessionImplicits.scala b/driver-scala/src/main/scala/org/mongodb/scala/ClientSessionImplicits.scala
index 9718b01c1a8..b8824dc31f5 100644
--- a/driver-scala/src/main/scala/org/mongodb/scala/ClientSessionImplicits.scala
+++ b/driver-scala/src/main/scala/org/mongodb/scala/ClientSessionImplicits.scala
@@ -33,7 +33,7 @@ trait ClientSessionImplicits {
     /**
      * Commit a transaction in the context of this session.
      *
-     * A transaction can only be commmited if one has first been started.
+     * A transaction can only be committed if one has first been started.
      */
     def commitTransaction(): SingleObservable[Unit] = clientSession.commitTransaction()
 
diff --git a/driver-sync/src/main/com/mongodb/client/ClientSession.java b/driver-sync/src/main/com/mongodb/client/ClientSession.java
index c095bdb0a40..d35ee570900 100644
--- a/driver-sync/src/main/com/mongodb/client/ClientSession.java
+++ b/driver-sync/src/main/com/mongodb/client/ClientSession.java
@@ -94,7 +94,7 @@ public interface ClientSession extends com.mongodb.session.ClientSession {
     void startTransaction(TransactionOptions transactionOptions);
 
     /**
-     * Commit a transaction in the context of this session.  A transaction can only be commmited if one has first been started.
+     * Commit a transaction in the context of this session.  A transaction can only be committed if one has first been started.
      *
      * @see MongoException#UNKNOWN_TRANSACTION_COMMIT_RESULT_LABEL
      * @mongodb.server.release 4.0

From 1950ee65225756f46c3bca1c37a8bea11154a9a1 Mon Sep 17 00:00:00 2001
From: Valentin Kovalenko <valentin.kovalenko@mongodb.com>
Date: Fri, 17 Apr 2026 18:09:45 -0600
Subject: [PATCH 3/3] Small consistency improvements suggested by AI

---
 driver-core/src/main/com/mongodb/ConnectionString.java    | 6 +++---
 driver-core/src/main/com/mongodb/MongoClientSettings.java | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/driver-core/src/main/com/mongodb/ConnectionString.java b/driver-core/src/main/com/mongodb/ConnectionString.java
index 39e60e03b5b..36ab59d469f 100644
--- a/driver-core/src/main/com/mongodb/ConnectionString.java
+++ b/driver-core/src/main/com/mongodb/ConnectionString.java
@@ -1474,7 +1474,7 @@ public WriteConcern getWriteConcern() {
      * getRetryWrites() method, which returned a primitive {@code boolean} value, and didn't allow callers to differentiate
      * between a false value and an unset value.
      *
-     * @return the retryWrites value, or null if unset
+     * @return the {@code retryWrites} value, or {@code null} if unset
      * @see #getMaxAdaptiveRetries()
      * @since 3.9
      * @mongodb.server.release 3.6
@@ -1488,7 +1488,7 @@ public Boolean getRetryWritesValue() {
      * Gets whether attempts to execute read commands should be retried if they fail due to a retryable error.
      * See {@link MongoClientSettings.Builder#retryReads(boolean)} for more information.
      *
-     * @return the retryReads value
+     * @return the {@code retryReads} value, or {@code null} if unset
      * @see #getMaxAdaptiveRetries()
      * @since 3.11
      * @mongodb.server.release 3.6
@@ -1502,7 +1502,7 @@ public Boolean getRetryReads() {
      * Gets the maximum number of retry attempts when encountering a retryable overload error.
      * See {@link MongoClientSettings.Builder#maxAdaptiveRetries(Integer)} for more information.
      *
-     * @return The {@code maxAdaptiveRetries} value.
+     * @return The {@code maxAdaptiveRetries} value, or {@code null} if unset.
      * @since 5.7
      */
     @Beta(Reason.CLIENT)
diff --git a/driver-core/src/main/com/mongodb/MongoClientSettings.java b/driver-core/src/main/com/mongodb/MongoClientSettings.java
index 1e013ff3cc0..c1b3c4a069a 100644
--- a/driver-core/src/main/com/mongodb/MongoClientSettings.java
+++ b/driver-core/src/main/com/mongodb/MongoClientSettings.java
@@ -945,7 +945,7 @@ public ReadConcern getReadConcern() {
     }
 
     /**
-     * The codec registry to use, or null if not set.
+     * The codec registry to use.
      *
      * @return the codec registry
      */