# TransactionCanceledException: Transaction cancelled, please refer cancellation reasons

AWS error fixes · Updated 16 November 2026

**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).

## 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

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.

## 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.

[About the CloudConsole app](https://cloudconsole.dev/aws-console-app) · [Download on the App Store](https://apps.apple.com/app/cloudconsole-for-aws/id6835419710)

## Sources

- [Amazon DynamoDB Transactions: how it works](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/transaction-apis.html)
- [TransactWriteItems API reference](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html)

## Related

- [ConditionalCheckFailedException: The conditional request failed](https://cloudconsole.dev/errors/dynamodb-conditionalcheckfailed)
- [ProvisionedThroughputExceededException](https://cloudconsole.dev/errors/dynamodb-provisionedthroughputexceeded)
- [aws dynamodb update-item](https://cloudconsole.dev/cli/dynamodb-update-item)
- [aws dynamodb put-item](https://cloudconsole.dev/cli/dynamodb-put-item)
- [CloudWatch alarm for DynamoDB UserErrors](https://cloudconsole.dev/alarms/dynamodb-usererrors)
- [ValidationException: Item size has exceeded the maximum allowed size](https://cloudconsole.dev/errors/dynamodb-item-size-exceeded)

---

Source: https://cloudconsole.dev/errors/dynamodb-transactioncanceled

CloudConsole is an independent iPhone and Android app for Amazon Web Services by Cloudconcur Ltd. It is not affiliated with Amazon Web Services.
