mongodb/node-mongodb-native · error · MongoUnexpectedServerResponseError

Selected server does not support retryable writes

Error message

Selected server does not support retryable writes

What it means

Thrown as a MongoUnexpectedServerResponseError during the retry loop after a new server is selected for a retryable write, when supportsRetryableWrites(server) returns false for the newly selected server. supportsRetryableWrites is false for standalone servers or servers lacking a logicalSessionTimeoutMinutes (no sessions support). This indicates the topology shifted under retry to a node that cannot honor retryable writes.

Solutions

  1. Disable retryWrites (retryWrites=false) if the deployment genuinely cannot support it.
  2. Ensure all members of the deployment are part of a replica set or sharded cluster with sessions enabled.
  3. Check that no standalone mongod is reachable at the configured addresses.
  4. Verify the server version supports sessions (3.6+) and that logicalSessionTimeoutMinutes is reported.

Example fix

// before
const uri = 'mongodb://host:27017/'; // standalone, retryWrites default

// after
const uri = 'mongodb://host:27017/?retryWrites=false';
Defensive patterns

Strategy: try-catch

Validate before calling

import { MongoClient } from 'mongodb';

const client = new MongoClient(uri);
await client.connect();
// If the deployment may contain standalones, disable retryWrites up front
if (!client.topology?.description) {
  // unable to determine; be conservative
  throw new Error('Could not verify topology supports retryable writes');
}

Try / catch

try {
  await collection.insertOne({ a: 1 });
} catch (err) {
  if (err instanceof MongoUnexpectedServerResponseError && /retryable writes/i.test(err.message)) {
    // failover selected an unsupported server; retry once with retryWrites off or report
  } else throw err;
}

Prevention

When it happens

Trigger: A retryable write fails with a retryable error (e.g. network error), the retry selects a different server (failover), and that server is a standalone or otherwise lacks retryable-writes support; the guard at execute_operation.ts:360 then fires. Also possible in mixed topologies where a node description reports no session support.

Common situations: Failover from a replica set to a standalone member; misconfigured sharded cluster with a standalone mongos-less node; topology description lagging behind reality; connecting to a single standalone while retryWrites defaults on.

Related errors

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

Appendix: source

Thrown at src/operations/execute_operation.ts:360

        (operationError.hasErrorLabel(MongoErrorLabel.SystemOverloadedError) &&
          topology.s.options.enableOverloadRetargeting)
      ) {
        deprioritizedServers.add(server.description);
      }

      server = await topology.selectServer(selector, {
        session,
        operationName: operation.commandName,
        deprioritizedServers,
        signal: operation.options.signal
      });

      if (
        hasWriteAspect &&
        !supportsRetryableWrites(server) &&
        !operationError.hasErrorLabel(MongoErrorLabel.SystemOverloadedError)
      ) {
        throw new MongoUnexpectedServerResponseError(
          'Selected server does not support retryable writes'
        );
      }

      // Batched operations must reset the batch before retry,
      // otherwise building a command will build the _next_ batch, not the current batch.
      if (operation.hasAspect(Aspect.COMMAND_BATCHING)) {
        operation.resetBatch();
      }
    }
  }

  throw (
    error ??
    new MongoRuntimeError(
      'Should never happen: operation execution loop terminated but no error was recorded.'
    )
  );

View on GitHub (pinned to dce7939f86)