Does enabling HA change lock timeouts to TransientTransactionError?

Question

Does enabling HA change lock timeouts to TransientTransactionError?

Alex Chetcuti 0

We're using Azure DocumentDB (free tier, nodeCount: 1, enableHa: false) with the MongoDB driver in C#. Under concurrent multi document transactions targeting the same document, we consistently get: MongoCommandException: Command update failed: canceling statement due to lock timeout. This error has no TransientTransactionError label, so session.WithTransactionAsync() does not retry it and bubbles as a 500 to the client.

We replicated the same workload against a local MongoDB replica set (Docker) and the same concurrent writes return TransientTransactionError instead, which WithTransactionAsync() retries automatically, resulting in zero failures.

Does enabling High Availability (enableHa: true) on an Azure DocumentDB cluster change the write conflict behavior from lock timeouts to TransientTransactionError? Or is HA purely for failover availability with no effect on how write conflicts are surfaced to the driver?

We want to understand whether upgrading to a paid tier with HA is the right path to making WithTransactionAsync() retry logic work correctly, or whether Azure DocumentDB's will always surface write conflicts as lock timeouts regardless of HA configuration.

0 comments

2 answers

Your answer

Answer 1

Ganesh Chelluri 190 Microsoft External Staff Moderator

Hi @Alex Chetcuti ,

High Availability in Azure DocumentDB is documented as an availability and failover feature. It maintains standby replicas of shards and can redirect connections to a standby shard if a primary shard becomes unresponsive. I do not see documentation stating that enabling HA changes transaction write-conflict or lock-timeout errors into MongoDB driver errors labeled TransientTransactionError.

Based on that, I would not treat upgrading to a paid tier with HA as the fix for WithTransactionAsync retry behavior. HA is useful for availability/failover resilience, but it is not documented as changing application-level transaction retry labels.

For this workload, please handle this lock-timeout path with explicit application retry logic and reduce concurrent transactions that update the same document/key where possible. The current error is not being surfaced with the TransientTransactionError label, so the driver’s automatic retry path may not run for this specific failure.

If you can share a minimal repro, the MongoDB C# driver version, and the full exception text including labels/error code with secrets removed, we can validate whether the observed error label behavior matches the current Azure DocumentDB implementation.

Verification:

Re-run the same concurrent transaction workload after adding explicit retry for the lock-timeout error path.
Confirm whether failures reduce or disappear.
Confirm whether the exception still arrives without the TransientTransactionError label.

Ganesh Chelluri 190 Reputation points Microsoft External Staff Moderator

2026-08-17T10:13:23.9666667+00:00

Hi @Alex Chetcuti ,

We haven’t received a response. Please let us know if you need any additional information or assistance from my side.
Alex Chetcuti 0 Reputation points

2026-08-19T12:19:12.5933333+00:00

Hi Ganesh,

Thanks for the clarification and for following up.

After evaluating this further, we’ve decided not to proceed with Azure DocumentDB for this workload. Our application relies heavily on concurrent multi-document transactions, and since the lock-timeout behavior is not surfaced as TransientTransactionError, the C# driver’s built-in WithTransactionAsync() retry mechanism cannot handle these conflicts as we need it to.

Rather than adding custom retry logic around this behavior, we’ve decided to move to another technology that better supports our concurrency and transaction requirements out of the box.

Thanks again for your help and for clarifying the behavior of HA. I appreciate the time you spent looking into this.

Best regards, Alex
Ganesh Chelluri 190 Reputation points Microsoft External Staff Moderator

2026-09-06T23:25:23.56+00:00

Hi @Alex Chetcuti ,

Thank you for the update and for sharing the outcome of your evaluation.

I understand your decision and appreciate you taking the time to confirm the results. Based on the behavior observed, it makes sense to choose the solution that best aligns with your application's concurrency and transaction requirements.

Thank you for engaging with the Microsoft Q&A community. I'll consider this thread resolved. If you have any additional Azure DocumentDB questions in the future, please feel free to open a new thread.

Answer 2

Hi @Alex Chetcuti

Thank you for reaching out to Microsoft Q&A. Based on the published documentation, I would not enable HA. Azure DocumentDB documents HA as synchronous standby replication and automatic shard failover, not as a setting that changes transaction write-conflict handling or MongoDB driver error labels. High availability in Azure DocumentDB

I would enable HA for its availability and failover benefits, not to address this retry behavior. The Azure DocumentDB error reference does not document this lock-timeout message or a TransientTransactionError labeling contract, so I would open an Azure support request before changing tiers or adding a custom retry classification. Include a minimal reproduction, region, service and driver versions, HA settings, and the complete command response so support can confirm whether this is intended behavior, a compatibility gap, or a service issue. Troubleshoot common issues in Azure DocumentDB

Please 'Upvote' (Thumbs-up) and 'Accept' as an answer if the response was helpful. This will help other community members facing the same issue.

Best regards, Andrew S Taylor