How to Fix MongoDB Error 225 (TransactionTooOld)
You get mongodb error 225 when a transaction runs past its time limit. You fix it by retrying the transaction and shortening your write operations. MongoDB names this failure TransactionTooOld in its official error catalog. The database puts it in the VoteAbortError and TwoPhaseDecisionAckError categories. It appears when nodes coordinate a multi-document write across a cluster. One node takes too long to vote or confirm a two-phase commit. The cluster then aborts the work to keep data safe and
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 get mongodb error 225 when a transaction runs past its time limit. You fix it by retrying the transaction and shortening your write operations.
MongoDB names this failure TransactionTooOld in its official error catalog. The database puts it in the VoteAbortError and TwoPhaseDecisionAckError categories. It appears when nodes coordinate a multi-document write across a cluster. One node takes too long to vote or confirm a two-phase commit. The cluster then aborts the work to keep data safe and consistent.
What causes mongodb error 225 in your cluster
Distributed transactions need every shard or replica set member to agree on time. When you start a transaction, the engine opens a snapshot of your data. That snapshot cannot keeps the session active forever because it holds memory and locks. If the transaction keeps the session active too long, the storage engine drops the old snapshot. When the coordinator asks to commit, the node replies with TransactionTooOld.
Two-phase commits make this timing even more strict for your database cluster. In a two-phase commit, a coordinator asks each shard to vote on the write. If a shard is slow, the vote arrives after the transaction window closes. That triggers the VoteAbortError path and cancels the entire write across all shards. In other cases, the decision acknowledgment arrives late, triggering the TwoPhaseDecisionAckError category.
Several everyday issues make a transaction run past its allowed time limit. A client app might pause between queries while waiting for an external service. Network delays between shards can slow down the two-phase commit messages. Heavy disk load or lock contention on one shard can also stall the vote. Even an ad-hoc query from an engineer can hold a transaction open too long.
How to diagnose and fix TransactionTooOld safely
Start by checking your database logs to see which shard aborted the commit. Look for slow queries or lock waits that happened right before the abort. Check if your app does slow network calls inside the open transaction block. Move any external API calls or heavy math outside the transaction boundary. Keep only the required database reads and writes inside the transaction itself.
MongoDB Authentication & Authorization + End-to-End Encryption: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
Next, make sure your app uses retry logic for transient transaction failures. When the database returns code 225, the client should start a fresh transaction. Do not try to reuse the old session snapshot after a vote abort. Splitting huge batch updates into smaller chunks also helps each commit finish fast.
How to inspect production state without adding risk
Engineers often need to check cluster state while debugging transaction timeouts in production. Do not hand out broad write privileges just to inspect a stalled workload. MongoDB grants access through role-based rules that apply down to the collection level. You can give an engineer the built-in read role on the target database.
The read role lets users run find, listCollections, listIndexes, dbStats, and collStats. It does not allow insert, update, remove, or dropCollection actions on your data. Reserve the readWrite role for services or tasks that must modify records. Also, if engineers run find queries during an incident, protect sensitive user fields. Data masking rewrites matched fields like emails, phone numbers, and card numbers in results.
Inspect MongoDB wire traffic in flight
Built-in MongoDB roles govern collection access at setup time. They cannot score command risk per call or mask sensitive document values on the fly. By design, hoop.dev sits inline in the MongoDB protocol next to your server as a sidecar for your MongoDB. On every production command from mongosh, drivers, or AI agents, hoop.dev decides whether to pass, mask, block, or hold it for human review.
First, hoop.dev guardrails block bad deletes, drops, and write pipelines or hold them for approval. Next, hoop.dev data masking rewrites sensitive values in returned documents in memory and logs each decision. Explore the repo on GitHub.
Frequently asked questions
What does MongoDB error code 225 mean?
Error 225 means TransactionTooOld in the official MongoDB error spec. It happens when a transaction exceeds its valid lifetime during a vote or acknowledgment.
Is it safe to retry a transaction after error 225?
Yes, you should retry the entire transaction from the beginning with a new snapshot. Because error 225 belongs to VoteAbortError, the database rolls back the partial changes.
What database role should engineers use to check collection stats?
Assign the built-in read role on the specific database they need to check. This role permits collStats and dbStats without allowing data changes like update or remove.
Related guides
In this post