Why is my TransactWriteItems API call failing in Amazon DynamoDB?

Last updated: 2022-09-07

My TransactWriteItems API call is failing and I want to know the root cause of the issue.


There are a number of reasons that a TransactWriteItems request might fail or be rejected by Amazon DynamoDB.

A condition in one of the condition expressions isn't met

If a condition that you set for one of the operations in your TransactWriteItems request isn't met, then all operations fail. TransactWriteItems is a synchronous write operation that groups up to 25 action requests. So, either all of the action requests succeed, or all of the action requests fail.

If you are experiencing this issue, then you receive an error message similar to this:

"message": "Transaction cancelled, please refer cancellation reasons for specific reasons [ConditionalCheckFailed, None, None, None] (Service: AmazonDynamoDBv2; Status Code: 400; Error Code: TransactionCanceledException;..."

To resolve this issue, make sure that all the conditions that you set for your request are satisfied.

The table in the TransactWriteItems request is in a different Region or account

TransactWriteItems requests allow you to work with items across different tables. But, you can't work with tables that are in different Regions or accounts. Make sure that you are working with tables that are in the same Region as the account where you are making the TransactWriteItems request from.

More than one action in the TransactWriteItems operation handles the same item

When more than one action in the TransactWriteItems operation handles the same item, then the request fails with a message similar to this:

"Transaction request cannot include multiple operations on one item"

So, for example if TransactWriteItems tries to run a ConditionCheck and Put operation on the same item, then the request fails. You can monitor this TransactionConflict exception by using the TransactionConflict metric for your DynamoDB table in Amazon CloudWatch.

There isn't enough provisioned capacity to complete the transaction

Like any other operation, a DynamoDB table might be throttled when you invoke the TransactWriteItems operation. For more information on resolving this issue, see Why is my on-demand Amazon DynamoDB table being throttled? and Why is my Amazon DynamoDB table being throttled?

A ValidationError occurred

If an item size becomes larger than 400 KB or a local secondary index (LSI) becomes too large, then a ValidationErrror occurs. Similarly, validation errors can occur because of changes made by the transaction. This means that the input fails to satisfy one or more constraints that are specified by the DynamoDB service. The validation error is accompanied by one of these messages, depending on which constraint isn't satisfied:

  • One or more parameter values are invalid.
  • The update expression attempts to update the secondary index key beyond allowed size limits.
  • The update expression attempts to update the secondary index key to an unsupported type.
  • An operand in the update expression has an incorrect data type.
  • The item to update has exceeded the maximum allowed size.
  • You are attempting to store a number with magnitude larger than the supported range, or number overflow.
  • There is a type mismatch for attribute to update.
  • Nesting levels have exceeded supported limits.
  • The document path provided in the update expression is invalid for update.
  • The provided expression refers to an attribute that doesn't exist in the item.

DynamoDB limits the size of each item that you can store in a table. If your application needs to store more data in an item than the size limit allows, compress one or more of the larger attributes. Or, break down the item into multiple items, indexed by sort keys. You can also store the item as an object in Amazon Simple Storage Service (Amazon S3). Then, store the Amazon S3 object identifier in your DynamoDB item. For more information, see Best practices for storing large items and attributes.

The aggregate size of the items in a transaction exceeds 4 MB

TransactWriteItems operations can't exceed 4 MB. This is a hard limit. For more information, see DynamoDB transactions.

A user error occurred

A user error, like an invalid data format, can occur for a number of reasons. For example, you might receive a 4xx error for ResourceNotFoundException because the TransactWriteItems operation can't find the underlying DynamoDB table or index. Or, the DynamoDB table or index might not be ACTIVE.

Note: When you use the AWS SDK for Java, DynamoDB lists cancellation reasons on the CancellationReasons property. This property isn't set for other languages. Transaction cancellation reasons are listed in the order of requested items. If an item has no error, it lists a NONE code and null message. For more information, see TransactWriteItems.

Did this article help?

Do you need billing or technical support?