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

  1. Commit or abort the current transaction (POST/PATCH /v1/databases/transactions/...) and create a fresh one, then stage the remaining operations there
  2. Split your work into chunks of at most databasesTransactionSize staged operations per transaction
  3. Check the transaction's 'operations' count via GET /v1/databases/transactions/:transactionId before staging to detect the boundary
  4. 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

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


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)