How to Fix MongoDB Error 267 (PreparedTransactionInProgress)
You get mongodb error 267 when a prepared transaction blocks a database operation. You fix it by waiting for the commit or aborting the stuck transaction. The official server name for this fault is PreparedTransactionInProgress. It occurs during distributed two-phase commits across a sharded cluster. When one shard holds a transaction in a prepared state, locks remain active. Conflicting operations cannot finish until the coordinator resolves that prepared state. What causes mongodb error 267
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 267 when a prepared transaction blocks a database operation. You fix it by waiting for the commit or aborting the stuck transaction.
The official server name for this fault is PreparedTransactionInProgress. It occurs during distributed two-phase commits across a sharded cluster. When one shard holds a transaction in a prepared state, locks remain active. Conflicting operations cannot finish until the coordinator resolves that prepared state.
What causes mongodb error 267 in sharded clusters
Sharded clusters use two-phase commits to change data across multiple shards at once. In the first phase, the transaction coordinator tells every participant shard to prepare. Each shard writes the changes to its local log and holds locks. At this stage, the transaction enters the prepared state.
In the second phase, the coordinator tells all shards to commit or abort. If a network drop or node election interrupts this step, the transaction stalls. It stays in the prepared state while waiting for the coordinator decision. If another command tries to change the locked resource, the database rejects it. The engine returns mongodb error 267 to protect data consistency across shards.
Admin commands often hit this roadblock during busy hours. Dropping a collection, changing an index, or moving a chunk can trigger it. Long-running app transactions also raise the risk of lock conflicts. If an app opens a multi-shard transaction and stalls, prepared locks pile up.
How to diagnose and fix prepared transaction locks safely
Start your check by inspecting active operations in the cluster. Look for sessions that hold prepared transactions for a long time. You do not need full admin rights to check basic collection stats. MongoDB uses roles to grant actions down to the collection level. The built-in read role grants read access to all non-system collections. It lets you list collections, list indexes, and check collection stats safely. It does not allow insert, update, remove, or drop collection actions.
Wait a few seconds before taking manual action on the cluster. Most prepared transactions finish on their own once the coordinator reconnects. Have your client app catch the error and retry with a short delay. Retrying is the safest fix for brief network blips during shard elections.
MongoDB Authentication & Authorization + End-to-End Encryption: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
If the prepared state never clears, check the health of every replica set. Look at the primary node on each shard involved in the transaction. A stalled secondary node or disk delay can block the majority write concern. Once the unhealthy shard recovers, the coordinator can finish the commit phase.
Sometimes a manual admin task triggers the error during a deployment. Pause the schema change or index build right away. Let the active app traffic drain and finish its two-phase commits. Then run your admin change during a quiet window with fewer multi-shard writes.
Avoid granting broad write roles to engineers who only inspect stuck sessions. The readWrite role allows data changes and lets users drop collections or indexes. Keep diagnostic users on read-only roles while they check cluster health. Only use elevated permissions when you must kill a stuck coordinator session.
How to prevent future two-phase commit stalls
Keep your multi-document transactions small and fast in your app code. Touch as few shards as possible in a single transaction block. When a transaction spans only one shard, the engine skips two-phase commits. That design avoids the prepared state and prevents this error code.
Set sensible time limits on all client transactions so locks cannot hang forever. Monitor replica set replication lag across every shard in your production cluster. Fast replication helps prepared transactions commit quickly and release their locks.
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
What does PreparedTransactionInProgress mean in MongoDB?
It means a multi-shard transaction is holding locks in the prepare phase. Another operation tried to conflict with that locked resource before the commit finished.
Can I fix mongodb error 267 by retrying the request?
Yes, retrying after a short wait works for most transient cases. The coordinator usually finishes the commit or abort within a few seconds.
Which role should engineers use to inspect collection state during this error?
Assign the built-in read role for safe checks on a database. It allows stats and index checks without allowing data changes or collection drops.
Related guides
In this post