TransactionCanceledException: Transaction cancelled, please refer cancellation reasons
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).
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
| Code | Meaning | What to do |
|---|---|---|
ConditionalCheckFailed | A ConditionExpression or ConditionCheck was false | Business logic: duplicate, stale version or insufficient balance. Do not blindly retry. |
TransactionConflict | Another transaction or write touched the same item at the same time | Retry with backoff; reduce contention on hot items |
ProvisionedThroughputExceeded / ThrottlingError | Not enough capacity for one of the items | Retry with backoff; check capacity (transactions consume double) |
ValidationError | Bad request for that action: wrong key, item too large, invalid expression | Fix the request |
ItemCollectionSizeLimitExceeded | A partition with a local secondary index hit its size limit | Redesign the key or index |
Most common real-world causes
- An intended guard fired. For example
attribute_not_exists(pk)on an idempotency record, orbalance >= :amounton a debit. Treat these as normal outcomes. - Contention on a shared item, such as a counter or an aggregate row every transaction updates. Under load this shows as
TransactionConflict. - A non-transactional write racing the transaction. A plain
UpdateItemon the same item during the transaction can cancel it. - Retries without an idempotency token, so a retried transaction sees its own earlier writes and fails its conditions.
Fixes
- Return the failing item: set
ReturnValuesOnConditionCheckFailuretoALL_OLDon each conditional action, and the reason entry includes the item that failed. - Use
ClientRequestTokenso 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-7f3c9aMonitoring
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.

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