appwrite/appwrite · error · Appwrite\Extend\Exception
transaction_limit_exceeded
transaction_limit_exceeded
Error message
Transaction already has $existing operations, adding 1 would exceed the maximum of $maxBatch
What it means
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.
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)
Example fix
// before: one transaction for every staged op
const tx = await createTransaction();
for (const doc of docs) {
await sdk.databases.incrementDocumentAttribute(dbId, colId, doc.id, 'views', 1, undefined, tx.$id);
// throws transaction_limit_exceeded once 'operations' hits the cap
}
// after: rotate transactions at the plan limit
let tx = await createTransaction();
let staged = 0;
for (const doc of docs) {
if (staged + 1 > TX_LIMIT) { // plan databasesTransactionSize
await commitTransaction(tx.$id);
tx = await createTransaction();
staged = 0;
}
await sdk.databases.incrementDocumentAttribute(dbId, colId, doc.id, 'views', 1, undefined, tx.$id);
staged++;
} Defensive patterns
Strategy: try-catch
Validate before calling
// before staging, confirm headroom on the transaction
const res = await fetch(`${endpoint}/databases/transactions/${txId}`, {
headers: { 'X-Appwrite-Project': projectId, 'X-Appwrite-Key': apiKey },
});
const tx = await res.json();
const canStage = tx.status === 'pending' && (tx.operations + 1) <= TX_LIMIT; // plan databasesTransactionSize
if (!canStage) { /* commit + create a new transaction */ } Try / catch
try {
await sdk.databases.incrementDocumentAttribute(dbId, colId, docId, attr, value, max, txId);
} catch (e) {
if (e.code === 'transaction_limit_exceeded') {
await commitTransaction(txId);
const tx = await createTransaction();
await sdk.databases.incrementDocumentAttribute(dbId, colId, docId, attr, value, max, tx.$id);
} else throw e;
} Prevention
- 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
When it happens
Trigger: 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.
Common situations: 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.
Related errors
- transaction_limit_exceeded
- transaction_limit_exceeded
- attribute_limit_exceeded
- transaction_limit_exceeded
- transaction_limit_exceeded
AI-assisted analysis of appwrite/appwrite@ca3c55abfe (2026-08-18).
Data as JSON: /api/errors/fd256d21ec20595c.
Report an issue: GitHub.
Appendix: source
Thrown at src/Appwrite/Platform/Modules/Databases/Http/Databases/Collections/Documents/Attribute/Increment.php:129
if ($transactionId !== null) {
$transaction = ($isAPIKey || $isPrivilegedUser)
? $authorization->skip(fn () => $dbForProject->getDocument('transactions', $transactionId))
: $dbForProject->getDocument('transactions', $transactionId);
if ($transaction->isEmpty() || $transaction->getAttribute('status', '') !== 'pending') {
throw new Exception(Exception::GENERAL_BAD_REQUEST, 'Invalid or non‑pending transaction');
}
$now = new \DateTime();
$expiresAt = new \DateTime($transaction->getAttribute('expiresAt', 'now'));
if ($now > $expiresAt) {
throw new Exception(Exception::TRANSACTION_EXPIRED);
}
// Enforce max operations per transaction
$maxBatch = $plan['databasesTransactionSize'] ?? APP_LIMIT_DATABASE_TRANSACTION;
$existing = $transaction->getAttribute('operations', 0);
if (($existing + 1) > $maxBatch) {
throw new Exception(
Exception::TRANSACTION_LIMIT_EXCEEDED,
'Transaction already has ' . $existing . ' operations, adding 1 would exceed the maximum of ' . $maxBatch
);
}
// Stage the operation in transaction logs
$staged = new Document([
'$id' => ID::unique(),
'databaseInternalId' => $database->getSequence(),
'collectionInternalId' => $collection->getSequence(),
'transactionInternalId' => $transaction->getSequence(),
'documentId' => $documentId,
'action' => 'increment',
'data' => [
$this->getAttributeKey() => $attribute,
'value' => $value,
'max' => $max,
],View on GitHub (pinned to ca3c55abfe)