Why do I get a "ConditionalCheckFailedException" error in DynamoDB?

Short description

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshoot AWS CLI errors. Also, make sure that you're using the most recent AWS CLI version.

The "ConditionalCheckFailedException" error might occur when you perform a conditional update for an item and the value of the attribute doesn't match the expected value. To troubleshoot this error, turn on the ReturnValuesOnConditionCheckFailure parameter to see what caused the failure. Then, resolve the error.

You can also get this error when you use optimistic locking with DynamoDBVersionAttribute. If the DynamoDBVersionAttribute version value on the server is different from the value on the client side, then you might get this error. To resolve this error, turn off optimistic locking. If you want to use optimistic locking, then make sure that the client side version number matches the server side version number.

Resolution

You can use the ReturnValuesOnConditionCheckFailure parameter for the update-item API call. Valid values for this parameter include ALL_OLD or NONE. To troubleshoot failed checks, set the ReturnValuesOnConditionCheckFailure parameter to ALL_OLD. If a conditional check fails, then DynamoDB returns the old item attributes from before the update.

Use the AWS SDK UpdateItem API call

Note: The ReturnValuesOnConditionCheckFailure parameter might be different based on the AWS SDK and programming language that you use.

In the following example, the Python SDK is used to update the ReturnValuesOnConditionCheckFailure parameter for an item in a DynamoDB table. For more information, see update_item on the Boto3 website.

import boto3

# Create a DynamoDB client
dynamodb = boto3.client('dynamodb')

# Define the table name and the key to update
table_name = 'my-table'
key = {'id': {'S': '123'}}

# Define the attribute to update and the new value
attribute_to_update = 'name'
new_value = {'S': 'John Doe'}

# Define the condition expression to check before updating the item
condition_expression = 'attribute_exists(#name)'
expression_attribute_names = {'#name': attribute_to_update}

# Update the item with the ReturnValuesOnConditionCheckFailure parameter set to 'ALL_OLD'
response = dynamodb.update_item(
TableName=table_name,
Key=key,
UpdateExpression=f'SET {attribute_to_update} = :new_value',
ConditionExpression=condition_expression,
ExpressionAttributeNames=expression_attribute_names,
ExpressionAttributeValues={':new_value': new_value},
ReturnValuesOnConditionCheckFailure='ALL_OLD'
)

# Check the response to see if the update was successful
if 'Attributes' in response:
print(f"Item updated successfully: {response['Attributes']}")
else:
print(f"Condition check failed, original item returned: {response['ResponseMetadata']}")

Use AWS CLI UpdateItem command

In the following example, the update-item AWS CLI command is used to update an item in the DynamoDB table. The ReturnValuesOnConditionCheckFailure parameter is set to ALL_OLD, and returns the original item in the response if the condition check fails. For more information, see update-item.

aws dynamodb update-item \
--table-name my-table \
--key '{"id": {"S": "123"}}' \
--update-expression "SET attribute1 = :value1" \
--expression-attribute-values '{":value1": {"S": "new-value"}}' \
--return-values-on-condition-check-failure ALL_OLD

Related information

Handle conditional write errors in high concurrency scenarios with Amazon DynamoDB

RequestSyntax

Conditional expression examples

Error messages and codes

Optional configuration settings for DynamoDBMapper