CloudConsole

TransactionCanceledException: Transaction cancelled, please refer cancellation reasons

Updated 16 November 2026 · How we write and check guides

Short answer

One or more actions in a TransactWriteItems or TransactGetItems call failed, so DynamoDB rolled back all of them. The exception carries a CancellationReasons list with one entry per action, in order; the entries that are not "None" tell you which item failed and why (usually ConditionalCheckFailed or TransactionConflict).

Most common real-world causes, in 4 steps: 1. An intended guard fired; 2. Contention on a shared item; 3. A…
The diagnosis and fix steps from this page, in the order to try them; commands and details are below.

Reading the error

An error occurred (TransactionCanceledException) when calling the
TransactWriteItems operation: Transaction cancelled, please refer
cancellation reasons for specific reasons [None, ConditionalCheckFailed, None]

The bracketed list lines up with the actions you sent. Here the second action's condition was false, and the first and third were fine but rolled back anyway. In SDKs the same list is available as structured data, which is what you should log:

try:
    client.transact_write_items(TransactItems=items)
except client.exceptions.TransactionCanceledException as e:
    for i, r in enumerate(e.response.get('CancellationReasons', [])):
        if r.get('Code') != 'None':
            print(i, r.get('Code'), r.get('Message'), r.get('Item'))

Cancellation reason codes

CodeMeaningWhat to do
ConditionalCheckFailedA ConditionExpression or ConditionCheck was falseBusiness logic: duplicate, stale version or insufficient balance. Do not blindly retry.
TransactionConflictAnother transaction or write touched the same item at the same timeRetry with backoff; reduce contention on hot items
ProvisionedThroughputExceeded / ThrottlingErrorNot enough capacity for one of the itemsRetry with backoff; check capacity (transactions consume double)
ValidationErrorBad request for that action: wrong key, item too large, invalid expressionFix the request
ItemCollectionSizeLimitExceededA partition with a local secondary index hit its size limitRedesign the key or index

Most common real-world causes

  1. An intended guard fired. For example attribute_not_exists(pk) on an idempotency record, or balance >= :amount on a debit. Treat these as normal outcomes.
  2. Contention on a shared item, such as a counter or an aggregate row every transaction updates. Under load this shows as TransactionConflict.
  3. A non-transactional write racing the transaction. A plain UpdateItem on the same item during the transaction can cancel it.
  4. Retries without an idempotency token, so a retried transaction sees its own earlier writes and fails its conditions.

Fixes

  • Return the failing item: set ReturnValuesOnConditionCheckFailure to ALL_OLD on each conditional action, and the reason entry includes the item that failed.
  • Use ClientRequestToken so retries of the same logical transaction within the idempotency window are not applied twice.
  • Retry only retryable codes (conflict and throttling) with exponential backoff and jitter.
  • Remove hot items from the transaction path: shard counters, or update aggregates asynchronously from a stream.
  • Keep transactions small. Each item is one more chance of conflict; there is a limit of 100 actions and 4 MB per transaction, and an item may appear only once per transaction (a second action on it is a ValidationException).

From the CLI the reasons appear in the message, which is enough for ad-hoc testing:

aws dynamodb transact-write-items \
  --transact-items file://transfer.json \
  --client-request-token transfer-7f3c9a

Monitoring

Conflicts are invisible in table-level throttle metrics. Log the reason codes with a counter per code so you can see whether cancellations are business rules (fine) or contention (a design problem). The TransactionConflict CloudWatch metric counts conflict rejections at the table level and is worth graphing during load tests.

Questions

Why was my DynamoDB transaction cancelled when only one item failed?

Transactions are all or nothing. If any action fails, DynamoDB cancels the whole transaction; the CancellationReasons list shows which action caused it and the rest show None.

Should I retry a TransactionCanceledException?

Only if the reason is TransactionConflict or throttling. ConditionalCheckFailed and ValidationError will fail again unless the data or request changes.

How many items can a DynamoDB transaction include?

Up to 100 actions, with a 4 MB total size limit at the time of writing, and each item can appear in only one action per transaction.

CloudConsole services list on a phone, for following up on TransactionCanceledException away from your desk
When this happens away from your desk

Cancelled transactions usually show up as failed checkouts or payments rather than as a DynamoDB alarm. CloudConsole, a phone app for AWS, is built to put the application's error alarms and log lines in front of you on your phone, which is where you would first notice the pattern.

Did it start after a deploy? What changed? on the app’s alarm screen lists the deploys and configuration changes from the hour before the alarm fired.

About the app → · Download on the App Store

Sources