How to fix MongoServerError: UnknownTransactionCommitResult in MongoDB

MongoDBINTERMEDIATEMEDIUMUpdated Dec 15, 2025· 108 views

MongoDB raises UnknownTransactionCommitResult when a transaction commit operation encounters a network error, server selection error, or write concern timeout, leaving the commit state uncertain. This error label signals that retrying the commit may succeed, as the transaction might have actually committed despite the error.

Quick fix

Fixes MongoServerError: UnknownTransactionCommitResult

const session = client.startSession();
try {
  await session.withTransaction(async () => {
    await collection1.insertOne({ name: "item1" }, { session });
    await collection2.updateOne(
      { id: 123 },
      { $set: { status: "processed" } },
      { session }
    );
  });
  console.log("Transaction committed successfully");
} catch (error) {
  console.error("Transaction failed after retries:", error);
} finally {
  await session.endSession();
}
  1. Use the Convenient Transaction API with automatic retry logic
  2. Implement manual retry logic if using the Core Transaction API
  3. Configure appropriate write concerns and timeouts
  4. Monitor network stability and replica set health
mongodb — error
const session = client.startSession();
try {
  await session.withTransaction(async () => {
    await collection1.insertOne({ name: "item1" }, { session });
    await collection2.updateOne(
      { id: 123 },
      { $set: { status: "processed" } },
      { session }
    );
  });
  console.log("Transaction committed successfully");
} catch (error) {
  console.error("Transaction failed after retries:", error);
} finally {
  await session.endSession();
}
MongoServerError: UnknownTransactionCommitResult

What this error means

The UnknownTransactionCommitResult error label is added by MongoDB drivers when a `commitTransaction` operation fails in a way that makes it impossible to determine whether the transaction was successfully committed. This occurs during network failures, server selection errors, write concern timeouts (including MaxTimeMSExpired), or other retryable errors during the commit phase. Unlike a definitive failure, this error means the transaction *might* have succeeded on the server but the client couldn't confirm it. The driver automatically labels these errors to signal that retry logic should be applied, as retrying the commit is safe and may succeed if the transaction already completed.

Typical symptoms

  • Transaction commits fail with UnknownTransactionCommitResult error label during network instability.
  • Write concern timeouts occur during commit, but the actual transaction state is uncertain.
  • Server selection errors happen during commit phase in replica set or sharded cluster deployments.
  • Application logs show commit failures but database inspection reveals some transactions did complete.

Common causes

  1. Network interruptions between the driver and MongoDB server during the commit operation.
  2. Write concern cannot be satisfied within the configured timeout (wtimeout), but the transaction may still have committed.
  3. Server selection fails during commit because no eligible replica set member is available to confirm the commit.
  4. MaxTimeMSExpired error occurs during commit, leaving the final state unknown.
  5. Transient network errors or connection pool issues prevent receiving the commit acknowledgment.

How to fix "MongoServerError: UnknownTransactionCommitResult"

1Use the Convenient Transaction API with automatic retry logic

Modern MongoDB drivers (4.2+) provide a callback-based transaction API that automatically retries both TransientTransactionError and UnknownTransactionCommitResult errors. This is the recommended approach:

javascript
const session = client.startSession();
try {
  await session.withTransaction(async () => {
    await collection1.insertOne({ name: "item1" }, { session });
    await collection2.updateOne(
      { id: 123 },
      { $set: { status: "processed" } },
      { session }
    );
  });
  console.log("Transaction committed successfully");
} catch (error) {
  console.error("Transaction failed after retries:", error);
} finally {
  await session.endSession();
}

The withTransaction helper automatically retries commit operations when UnknownTransactionCommitResult is encountered, eliminating the need for manual retry logic.

2Implement manual retry logic if using the Core Transaction API

If you're using the Core Transaction API directly, you must implement retry logic for UnknownTransactionCommitResult errors:

javascript
const session = client.startSession();
session.startTransaction({
  readConcern: { level: "snapshot" },
  writeConcern: { w: "majority" }
});

try {
  await collection1.insertOne({ name: "item1" }, { session });
  await collection2.updateOne(
    { id: 123 },
    { $set: { status: "processed" } },
    { session }
  );

  // Retry commit on UnknownTransactionCommitResult
  await commitWithRetry(session);
  console.log("Transaction committed");
} catch (error) {
  await session.abortTransaction();
  throw error;
} finally {
  await session.endSession();
}

async function commitWithRetry(session) {
  while (true) {
    try {
      await session.commitTransaction();
      break;
    } catch (error) {
      if (error.hasErrorLabel && error.hasErrorLabel("UnknownTransactionCommitResult")) {
        console.log("UnknownTransactionCommitResult, retrying commit...");
        continue;
      }
      throw error;
    }
  }
}

This pattern retries the commit until it succeeds or fails with a different error.

3Configure appropriate write concerns and timeouts

Reduce UnknownTransactionCommitResult frequency by configuring write concerns and timeouts that match your deployment:

javascript
const session = client.startSession();
await session.withTransaction(
  async () => {
    await collection.insertOne({ data: "value" }, { session });
  },
  {
    readConcern: { level: "snapshot" },
    writeConcern: { w: "majority", wtimeout: 5000 },
    maxCommitTimeMS: 10000
  }
);
await session.endSession();

Set wtimeout to allow sufficient time for write concern propagation in your replica set. Use maxCommitTimeMS to limit how long the driver waits for commit acknowledgment. Monitor network latency and adjust timeouts accordingly.

4Monitor network stability and replica set health

Check for underlying infrastructure issues that cause UnknownTransactionCommitResult:

bash
# Check replica set status
mongosh --eval "rs.status()"

# Monitor network latency between application and database
ping your-mongodb-server.com

# Check for connection pool exhaustion
mongosh --eval "db.serverStatus().connections"

Look for:
- Replica set members in RECOVERING or DOWN state
- High network latency (>100ms consistently)
- Connection pool saturation
- Write concern propagation delays

Address network issues, scale your replica set, or adjust connection pool settings to reduce commit uncertainty.

Advanced notes

The UnknownTransactionCommitResult error label is part of MongoDB's transaction retry specification. When drivers retry commits with this label, they should use a majority write concern to prevent transaction double-application. Note that drivers do NOT automatically retry write concern timeout errors indefinitely due to the implicit doubling of wtimeout with each retry. For production systems, implement idempotency in your transaction logic so that if a commit retry applies a transaction twice (in rare edge cases), your application state remains consistent. Consider using the newer withTransaction API callback pattern rather than manual transaction management, as it includes battle-tested retry logic that handles both TransientTransactionError and UnknownTransactionCommitResult correctly.

Frequently asked questions

What does "MongoServerError: UnknownTransactionCommitResult" mean?
The UnknownTransactionCommitResult error label is added by MongoDB drivers when a commitTransaction operation fails in a way that makes it impossible to determine whether the transaction was successfully committed. This occurs during network failures, server selection errors, write concern timeouts (including MaxTimeMSExpired), or other retryable errors during the commit phase. Unlike a definitive failure, this error means the transaction might have succeeded on the server but the client couldn't confirm it.
How do I fix "MongoServerError: UnknownTransactionCommitResult"?
MongoDB raises UnknownTransactionCommitResult when a transaction commit operation encounters a network error, server selection error, or write concern timeout, leaving the commit state uncertain. This error label signals that retrying the commit may succeed, as the transaction might have actually committed despite the error.
What causes "MongoServerError: UnknownTransactionCommitResult"?
Network interruptions between the driver and MongoDB server during the commit operation. Write concern cannot be satisfied within the configured timeout (wtimeout), but the transaction may still have committed. Server selection fails during commit because no eligible replica set member is available to confirm the commit.
Is the "MongoServerError: UnknownTransactionCommitResult" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading