{"record":{"id":"bd7f4d0eaa4c525b","repo":"payloadcms/payload","slug":"error-cannot-begin-transaction-err-message","errorCode":null,"errorMessage":"Error: cannot begin transaction: ${err.message}","messagePattern":"Error: cannot begin transaction: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/drizzle/src/transactions/beginTransaction.ts","lineNumber":67,"sourceCode":"        // Connection failed before callback ran - reject instead of hanging forever\n        transactionFailed(err)\n      })\n\n    // Need to wait until the transaction is ready\n    // before binding its `resolve` and `reject` methods below\n    await new Promise<void>((res, rej) => {\n      transactionReady = res\n      transactionFailed = rej\n    })\n\n    this.sessions[id] = {\n      db: transaction,\n      reject,\n      resolve,\n    }\n  } catch (err) {\n    this.payload.logger.error({ err, msg: `Error: cannot begin transaction: ${err.message}` })\n    throw new Error(`Error: cannot begin transaction: ${err.message}`)\n  }\n\n  return id\n}\n","sourceCodeStart":49,"sourceCodeEnd":72,"githubUrl":"https://github.com/payloadcms/payload/blob/00c58b35c0ed348ddc22daabf467b139727214fd/packages/drizzle/src/transactions/beginTransaction.ts#L49-L72","documentation":"Thrown by beginTransaction when the underlying Drizzle/driver call to open a transaction fails. The adapter awaits a readiness promise that is rejected by the driver's .catch handler, and the thrown error wraps the original driver message. Root causes are infrastructure-level: connection pool exhaustion, the DB refusing connections, a dead server, or a driver bug.","triggerScenarios":"Any Payload write operation that runs inside a transaction (create/update/delete with default transaction behavior) at a moment when the DB cannot start a transaction — pool full, DB down, network partition, max_connections reached.","commonSituations":"DB under heavy load; misconfigured pool size; DB restarted while the app held idle connections; running migrations against an unreachable database URL.","solutions":["Inspect the wrapped err.message to find the driver-level cause (connection refused, too many connections, etc.) and address that.","Increase the connection pool size / database max_connections, or reduce concurrency of write operations.","Verify the database is reachable and credentials/URL are correct (check pool health and network).","Retry the request after a brief backoff for transient connection failures."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"async function checkPool(db) {\n  // run a trivial query before issuing transactional writes\n  await db.execute('SELECT 1')\n}","typeGuard":null,"tryCatchPattern":"try {\n  await payload.create({ collection, data })\n} catch (err) {\n  if (/cannot begin transaction/.test(err.message)) {\n    // backoff and retry once; surface persistent failures to ops\n  } else throw err\n}","preventionTips":["Size the connection pool to match DB max_connections.","Monitor pool wait time and connection errors.","Keep transactions short to reduce pool pressure."],"tags":["transaction","database","connection","infrastructure"],"backgroundTag":null,"analyzedSha":"00c58b35c0ed348ddc22daabf467b139727214fd","analyzedAt":"2026-08-12T20:45:03.758Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}