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.
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.
Modern MongoDB drivers (4.2+) provide a callback-based transaction API that automatically retries both TransientTransactionError and UnknownTransactionCommitResult errors. This is the recommended approach:
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.
If you're using the Core Transaction API directly, you must implement retry logic for UnknownTransactionCommitResult errors:
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.
Reduce UnknownTransactionCommitResult frequency by configuring write concerns and timeouts that match your deployment:
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.
Check for underlying infrastructure issues that cause UnknownTransactionCommitResult:
# 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.
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.
StaleShardVersion: shard version mismatch
How to fix "StaleShardVersion: shard version mismatch" in MongoDB
MongoOperationTimeoutError: Operation timed out
How to fix "MongoOperationTimeoutError: Operation timed out" in MongoDB
MongoServerError: PlanExecutor error during aggregation :: caused by :: Sort exceeded memory limit of 104857600 bytes, but did not opt in to external sorting. Aborting operation.
How to fix "QueryExceededMemoryLimitNoDiskUseAllowed" in MongoDB
MissingSchemaError: Schema hasn't been registered for model
How to fix "MissingSchemaError: Schema hasn't been registered for model" in MongoDB/Mongoose
CastError: Cast to ObjectId failed for value "abc123" at path "_id"
How to fix "CastError: Cast to ObjectId failed" in MongoDB