How to fix MongoServerError: UnknownTransactionCommitResult in MongoDB

MongoDBINTERMEDIATEMEDIUM

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 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.

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.

How to fix MongoServerError: UnknownTransactionCommitResult in MongoDB

What this error means

Typical symptoms

Common causes

How to fix "MongoServerError: UnknownTransactionCommitResult"

Advanced notes

Related errors

Official resources & further reading