How to Fix MongoDB Error 311 (TransactionCoordinatorCanceled)
You see mongodb error 311 when a multi-shard transaction coordinator cancels its active work. You fix it by retrying the transaction after your cluster stabilizes. MongoDB names this error TransactionCoordinatorCanceled and puts it in the InternalOnly category. The database uses this code inside the cluster during shard tasks. Your app rarely sees it unless a coordinator steps down mid-flight. What causes mongodb error 311 in your cluster A sharded cluster uses a coordinator node to manage w
Your coding agents run with your access.
Claude Code reaches prod with a developer's credentials, and approval prompts get clicked through. hoop.dev checks every query, masks sensitive data, and holds risky changes for a human.
You see mongodb error 311 when a multi-shard transaction coordinator cancels its active work. You fix it by retrying the transaction after your cluster stabilizes.
MongoDB names this error TransactionCoordinatorCanceled and puts it in the InternalOnly category. The database uses this code inside the cluster during shard tasks. Your app rarely sees it unless a coordinator steps down mid-flight.
What causes mongodb error 311 in your cluster
A sharded cluster uses a coordinator node to manage writes across multiple shards. That node tracks every shard that takes part in the transaction. If the primary node on that shard steps down, the coordinator stops.
The engine then throws code 311 to cancel the local coordinator task. Network drops between shards can also trigger this internal stop signal. A replica set election during a write will cause the same issue.
High load on the primary node can delay heartbeats between cluster members. When heartbeats fail, the cluster starts an election to pick a new primary. The old primary cancels its coordinator work and logs this specific error.
Planned maintenance or rolling restarts also force primary nodes to step down. When a node steps down, it must abort pending coordinator tasks right away. This protects your data from split writes across different shards.
How to diagnose the failure safely in production
Start by checking your server logs around the time of the failure. Look for replica set stepdowns, elections, or network timeouts between your shards. These events show why the coordinator had to stop its work.
Do not give engineers broad admin rights just to inspect cluster health. MongoDB grants access through roles that define actions on specific resources. A role applies to its database and works down to the collection level.
For safe checks, assign the built-in read role on the target database. This role lets users run find, listCollections, listIndexes, dbStats, and collStats actions. It blocks insert, update, remove, and dropCollection actions so data stays safe.
MongoDB Authentication & Authorization + End-to-End Encryption: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
Note that Atlas users have different built-in roles than self-hosted database users. Both systems build their roles from the exact same set of privilege actions. Pick the smallest role that lets your team view the needed stats.
If your team queries user collections during checks, protect sensitive fields first. Data masking rewrites matched fields like emails, phone numbers, and card numbers. This keeps private data safe in results while engineers inspect failed runs.
How to fix and prevent coordinator cancellations
The best fix in your app is to use retryable writes and transactions. Official drivers can catch transient coordinator stops and run the transaction again. Make sure your app logic handles transaction retries without creating duplicate records.
Keep your multi-shard transactions short and fast to reduce the risk window. Long transactions hold locks longer and face a higher chance of stepdowns. Break huge batch updates into smaller writes that finish in milliseconds.
Check your network links and server CPU usage across all shard nodes. Fixing disk lag and memory pressure stops false elections during peak traffic. Schedule cluster upgrades and index builds during your lowest traffic hours.
When an engineer needs write rights to fix stuck data, use care. The readWrite role adds insert, update, and remove actions to the read role. Grant this role only for the fix, then remove it right away.
Add command guardrails and field masking beside MongoDB
Collection roles and IP rules control who connects to MongoDB. Yet an active client or agent session can still run a pipeline that writes data or reads raw personal fields. In practice, hoop.dev sits inline in the wire protocol beside your database as a sidecar for your MongoDB. For every command an agent or human sends in production, hoop.dev decides to pass, mask, block, or escalate it for review.
Using hoop.dev MongoDB controls, guardrails refuse banned commands before they run or hold risky calls for approval, and data masking rewrites matched fields in returned documents in memory. Furthermore, hoop.dev holds SOC 2 Type II, is MIT licensed, and generates evidence for GDPR, HIPAA, and PCI DSS programs. View the project on GitHub.
Frequently asked questions
Is error 311 a bug in my app code?
No, code 311 is an internal MongoDB signal called TransactionCoordinatorCanceled. It means a shard primary stepped down or lost contact during a transaction. Your app just needs to retry the aborted transaction once the cluster settles.
Can I fix code 311 by changing user permissions?
No, role changes will not stop a transaction coordinator from canceling work. Still, using the read role lets your team check dbStats and collStats safely. This helps you find the root cluster issue without risking accidental writes.
How do I stop this error from happening again?
Keep transactions small so they finish fast and avoid election windows. Check your shard nodes for high CPU or network drops that cause stepdowns. Ensure your database driver is set up to retry transient transaction failures.
Related guides
In this post