{"record":{"id":"fd256d21ec20595c","repo":"appwrite/appwrite","slug":"transaction-limit-exceeded-fd256d","errorCode":"transaction_limit_exceeded","errorMessage":"Transaction already has $existing operations, adding 1 would exceed the maximum of $maxBatch","messagePattern":"Transaction already has \\$existing operations, adding 1 would exceed the maximum of \\$maxBatch","errorType":"exception","errorClass":"Appwrite\\Extend\\Exception","httpStatus":400,"severity":"error","filePath":"src/Appwrite/Platform/Modules/Databases/Http/Databases/Collections/Documents/Attribute/Increment.php","lineNumber":129,"sourceCode":"        if ($transactionId !== null) {\n            $transaction = ($isAPIKey || $isPrivilegedUser)\n                ? $authorization->skip(fn () => $dbForProject->getDocument('transactions', $transactionId))\n                : $dbForProject->getDocument('transactions', $transactionId);\n            if ($transaction->isEmpty() || $transaction->getAttribute('status', '') !== 'pending') {\n                throw new Exception(Exception::GENERAL_BAD_REQUEST, 'Invalid or non‑pending transaction');\n            }\n\n            $now = new \\DateTime();\n            $expiresAt = new \\DateTime($transaction->getAttribute('expiresAt', 'now'));\n            if ($now > $expiresAt) {\n                throw new Exception(Exception::TRANSACTION_EXPIRED);\n            }\n\n            // Enforce max operations per transaction\n            $maxBatch = $plan['databasesTransactionSize'] ?? APP_LIMIT_DATABASE_TRANSACTION;\n            $existing = $transaction->getAttribute('operations', 0);\n            if (($existing + 1) > $maxBatch) {\n                throw new Exception(\n                    Exception::TRANSACTION_LIMIT_EXCEEDED,\n                    'Transaction already has ' . $existing . ' operations, adding 1 would exceed the maximum of ' . $maxBatch\n                );\n            }\n\n            // Stage the operation in transaction logs\n            $staged = new Document([\n                '$id' => ID::unique(),\n                'databaseInternalId' => $database->getSequence(),\n                'collectionInternalId' => $collection->getSequence(),\n                'transactionInternalId' => $transaction->getSequence(),\n                'documentId' => $documentId,\n                'action' => 'increment',\n                'data' => [\n                    $this->getAttributeKey() => $attribute,\n                    'value' => $value,\n                    'max' => $max,\n                ],","sourceCodeStart":111,"sourceCodeEnd":147,"githubUrl":"https://github.com/appwrite/appwrite/blob/ca3c55abfe2c8014937fdf778716af4524f2fcfc/src/Appwrite/Platform/Modules/Databases/Http/Databases/Collections/Documents/Attribute/Increment.php#L111-L147","documentation":"Thrown by PATCH /v1/databases/:databaseId/collections/:collectionId/documents/:documentId/:attribute/increment when a transactionId is supplied and the referenced transaction already holds the maximum number of staged operations. Each staged call writes a transactionLogs entry and atomically bumps the transaction's 'operations' counter; the cap comes from the project plan's databasesTransactionSize (falling back to APP_LIMIT_DATABASE_TRANSACTION). The check is (existing + 1) > maxBatch, so the operation is rejected before anything is written and the transaction is left untouched.","triggerScenarios":"Calling the increment endpoint with a transactionId whose 'transactions' document already reports 'operations' equal to the plan limit (e.g. staging the 101st write when the cap is 100). Happens in loops that stage create/update/delete/increment calls one by one against the same transactionId.","commonSituations":"Batch imports or sync jobs funneling hundreds of writes through one long-lived transaction; self-hosted installs relying on the default APP_LIMIT_DATABASE_TRANSACTION constant; cloud projects hitting their plan's transaction size; reusing a transactionId after other endpoints already filled it.","solutions":["Commit or abort the current transaction (POST/PATCH /v1/databases/transactions/...) and create a fresh one, then stage the remaining operations there","Split your work into chunks of at most databasesTransactionSize staged operations per transaction","Check the transaction's 'operations' count via GET /v1/databases/transactions/:transactionId before staging to detect the boundary","If the workload genuinely needs more ops per transaction, move to a plan with a higher databasesTransactionSize (or raise the configured limit on self-hosted)"],"exampleFix":"// before: one transaction for every staged op\nconst tx = await createTransaction();\nfor (const doc of docs) {\n  await sdk.databases.incrementDocumentAttribute(dbId, colId, doc.id, 'views', 1, undefined, tx.$id);\n  // throws transaction_limit_exceeded once 'operations' hits the cap\n}\n\n// after: rotate transactions at the plan limit\nlet tx = await createTransaction();\nlet staged = 0;\nfor (const doc of docs) {\n  if (staged + 1 > TX_LIMIT) { // plan databasesTransactionSize\n    await commitTransaction(tx.$id);\n    tx = await createTransaction();\n    staged = 0;\n  }\n  await sdk.databases.incrementDocumentAttribute(dbId, colId, doc.id, 'views', 1, undefined, tx.$id);\n  staged++;\n}","handlingStrategy":"try-catch","validationCode":"// before staging, confirm headroom on the transaction\nconst res = await fetch(`${endpoint}/databases/transactions/${txId}`, {\n  headers: { 'X-Appwrite-Project': projectId, 'X-Appwrite-Key': apiKey },\n});\nconst tx = await res.json();\nconst canStage = tx.status === 'pending' && (tx.operations + 1) <= TX_LIMIT; // plan databasesTransactionSize\nif (!canStage) { /* commit + create a new transaction */ }","typeGuard":null,"tryCatchPattern":"try {\n  await sdk.databases.incrementDocumentAttribute(dbId, colId, docId, attr, value, max, txId);\n} catch (e) {\n  if (e.code === 'transaction_limit_exceeded') {\n    await commitTransaction(txId);\n    const tx = await createTransaction();\n    await sdk.databases.incrementDocumentAttribute(dbId, colId, docId, attr, value, max, tx.$id);\n  } else throw e;\n}","preventionTips":["Track the number of staged operations client-side and rotate transactions before the plan's databasesTransactionSize","Treat a transaction as a short unit of work: create, stage a bounded number of ops, commit","Never cache or reuse one transactionId across independent requests or sessions"],"tags":["databases","transactions","limits","increment","staging"],"backgroundTag":"transaction-batch-limit-exceeded","analyzedSha":"ca3c55abfe2c8014937fdf778716af4524f2fcfc","analyzedAt":"2026-08-18T21:34:56.994Z","contentChangedAt":"2026-08-18T21:34:56.994Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}