Why does my TransactWriteItems API call fail in Amazon DynamoDB?

Resolution

The TransactWriteItems API request can fail or be rejected by DynamoDB for various reasons. See the following resolutions for troubleshooting steps. 

The condition expression contains a condition that 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. The TransactWriteItems request is a synchronous write operation that groups up to 25 action requests. Either all the action requests succeed, or all the action requests fail.

If your request fails because of this issue, then you receive an error message similar to the following:

"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 that you're working with is in a different Region or account

TransactWriteItems requests allow you to work with items across different tables. But you can only work with tables that are in the same AWS Region and account that sent the request. To resolve this issue, work only with tables that are in the same AWS Region as the AWS account that you make the TransactWriteItems request from.

The same item is handled by multiple actions in the TransactWriteItems operation

If more than one action in the TransactWriteItems operation handles the same item, then the request fails and you get an error message similar to the following:

"Transaction request cannot include multiple operations on one item"

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

Conflict between concurrent TransactWriteItems requests

A transactional conflict occurs because of concurrent item-level requests for an item within multiple Transactions. Transaction conflicts can occur for the following reasons:

• A PutItem, UpdateItem, or DeleteItem request for an item conflicts with an ongoing TransactWriteItems request that includes the same item.
• An item within a TransactWriteItems request is part of another ongoing TransactWriteItems request.

If a PutItem, UpdateItem, or DeleteItem request is rejected for this reason, then the request fails with a TransactionConflictException. But if an item-level request within TransactWriteItems or TransactGetItems is rejected for a different reason, then the request fails with a TransactionCanceledException.

There isn't enough provisioned capacity to complete the transaction

If you invoke the TransactWriteItems request when there isn't enough provisioned capacity, then the DynamoDB table is throttled. For more information about throttling, see Why is my on-demand DynamoDB table throttling? and Why is my Amazon DynamoDB provisioned table throttled?

Transactions fail due to IdempotentParameterMismatch exception

You can include an optional client token in your TransactWriteItems request to make sure that the requests are idempotent. Idempotent transactions can help to prevent application errors when the same operation is submitted multiple times because of a connection timeout or other connectivity issues.

A client token is valid for 10 minutes after the request that uses it finishes. If the request with that token repeats within the 10 minute window but changes some parameter within the transaction, then DynamoDB returns an IdempotentParameterMismatch exception.

A ValidationError occurred

If an item's size becomes larger than 400 KB or a local secondary index (LSI) becomes too large, then you get a ValidationError. DynamoDB limits the size of each item that you can store in a table. If your application must store more data in an item than the size limit allows, then compress one or more of the larger attributes. Or, break down the large item into multiple smaller items, indexed by sort keys. You can also store the item as an object in an Amazon Simple Storage Service (Amazon S3) bucket. After you do that, you can then store the Amazon S3 object identifier in your DynamoDB item. For more information, see Best practices for storing large items and attributes.

Validation errors can also occur because of changes made by the transaction. This means that the parameters in the request don't satisfy one or more constraints that are specified by the DynamoDB service. For more information on the types of constraints and their associated error messages, see the documentation for Class TransactionCanceledException.

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

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

A 4xx error occurred

A user error, such as a non-valid data format, can occur for a number of reasons. For example, you might receive a 4xx error for a ResourceNotFoundException error because the TransactWriteItems operation can't find the underlying DynamoDB table or index. Or, the DynamoDB table or index might not have the ACTIVE status.

Note: When you use the AWS SDK for Java, DynamoDB lists cancelation reasons on the CancellationReasons property. This property isn't set for other SDK languages. Transaction cancelation reasons are listed in the order of requested items.

A 5xx error occurred

Transactions can also fail due to system errors that are logged as 5xx errors. You get these errors when the service is unable to serve the request. These errors can occur for various reasons, such as transient network issues in the fleet, infrastructure issues, storage node related issues, and more. For more information, see Troubleshooting internal server errors in Amazon DynamoDB.

Related information

Common errors

TransactWriteItems API