payloadcms / payloadcms/payload

MongoDB TransientTransactionError / WriteConflict is not retried for Payload Local API writes

Open
#16,766 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

db: mongodb stale status: needs-triage v3
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
  1. 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.