payloadcms / payloadcms/payload
MongoDB TransientTransactionError / WriteConflict is not retried for Payload Local API writes
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 44.8k
- Forks
- 4.2k
- Avg merge
- 2d 21h
- Merged PRs (30d)
- 53
Description
Describe the Bug
Payload starts MongoDB transactions by default for Local API write operations, but when MongoDB throws a retryable transaction error such as TransientTransactionError / WriteConflict, Payload aborts the transaction and rethrows the error instead of retrying the whole transaction body.
MongoDB treats WriteConflict inside transactions as expected optimistic concurrency behavior. The recommended handling is to retry the full transaction when the error has the TransientTransactionError label. The MongoDB driver's higher-level session.withTransaction() API does this retry behavior automatically.
❌ In Payload, the current flow appears to be manual transaction handling:
const shouldCommit = !args.disableTransaction && await initTransaction(args.req)
try {
const result = await operation(args)
if (shouldCommit) {
await commitTransaction(args.req)
}
return result
} catch (err) {
if (shouldCommit) {
await killTransaction(args.req)
}
throw err
}
✅ Expected flow:
await runWithTransactionRetry(async () => { // ‼️
const shouldCommit = !args.disableTransaction && await initTransaction(args.req)
try {
const result = await operation(args)
if (shouldCommit) {
await commitTransaction(args.req)
}
return result
} catch (err) {
if (shouldCommit) {
await killTransaction(args.req)
}
throw err
}
})
Link to the code that reproduces this issue
https://github.com/dolanoadriano/payload-write-conflict-repro
Reproduction Steps
- Run:
pnpm install
pnpm test:int _community
Which area(s) are affected?
db: mongodb
Environment Info
Binaries:
Node: 24.14.0
npm: 11.9.0
Yarn: N/A
pnpm: 11.1.1
Relevant Packages:
payload: 3.80.0
Operating System:
Platform: darwin
Arch: arm64
Version: Darwin Kernel Version 25.3.0: Wed Jan 28 20:54:38 PST 2026; root:xnu-12377.91.3~2/RELEASE_ARM64_T6050
Available memory (MB): 24576
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by running pnpm test:int _community and locating the Local API transaction flow around initTransaction, commitTransaction, and killTransaction. Verify how MongoDB transaction errors are surfaced, then ensure the full operation is retried for the reported retryable errors while preserving transaction cleanup and disableTransaction; the reproduction repository provides the expected failure case.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- mongodb, typescript
- Domain
- backend, databases
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 50/100