AWS

DynamoDBConditionalCheckFailedException - DynamoDB Conditional Check Failed

Getting a **DynamoDBConditionalCheckFailedException** means your conditional write operation (PutItem, UpdateItem, DeleteItem) failed because the condition expression evaluated to false—the item doesn't match your expected state, doesn't exist when expected, or was modified by another operation. This client-side error (4xx) happens when AWS validates conditional expressions. Most common when item attribute values don't match expectations, but also appears when items don't exist when expected, version checks fail, optimistic locking conflicts occur, or condition expressions are incorrect.

#Common Causes

→Identity: IAM policy allows DynamoDB write but condition fails. Service Control Policy (SCP) enforces conditional checks.
→Network: VPC endpoint DynamoDB conditional restrictions. Concurrent modification conflicts.
→Limits: Condition expression evaluated to false. Item does not exist when expected. Item attribute value mismatch. Version check failed. Optimistic locking conflict.

✓Solutions

1Step 1: Diagnose - Check exact error message: AWS usually specifies which condition failed. Review condition expression. Check if item exists. Verify attribute values.
2Step 2: Diagnose - Get current item state: aws dynamodb get-item --table-name TABLE_NAME --key '{"id":{"S":"123"}}' --output json. Compare with expected state. Check attribute values.
3Step 3: Diagnose - Review condition expression: Verify condition expression syntax. Check if using ExpressionAttributeNames for reserved words. Verify ExpressionAttributeValues are correct.
4Step 4: Fix - Correct condition expression: Update condition to match actual item state. Use ExpressionAttributeNames for reserved words: #status instead of status. Verify attribute values match.
5Step 5: Fix - Implement retry logic: Retry with exponential backoff. Get current item state before retry. Update condition based on current state. Or use DynamoDB transactions for atomic operations.

</>Code Examples

Check Current Item State Before Conditional Update

1#!/bin/bash
2TABLE_NAME="my-table"
3ITEM_KEY='{"id":{"S":"123"}}'
4
5echo "=== Getting Current Item State ==="
6aws dynamodb get-item \
7  --table-name ${TABLE_NAME} \
8  --key ${ITEM_KEY} \
9  --output json | jq '.'
10
11# Check specific attribute value
12echo "\n=== Checking Attribute Value ==="
13CURRENT_STATUS=$(aws dynamodb get-item \
14  --table-name ${TABLE_NAME} \
15  --key ${ITEM_KEY} \
16  --query 'Item.status.S' \
17  --output text)
18
19echo "Current status: ${CURRENT_STATUS}"
20
21# Verify condition will pass
22EXPECTED_STATUS="pending"
23if [ "${CURRENT_STATUS}" = "${EXPECTED_STATUS}" ]; then
24  echo "✓ Condition will pass (status is ${EXPECTED_STATUS})"
25else
26  echo "✗ Condition will fail (status is ${CURRENT_STATUS}, expected ${EXPECTED_STATUS})"
27  echo "Update condition expression to match current state"
28fi

Use ExpressionAttributeNames for Reserved Words

1#!/bin/bash
2TABLE_NAME="my-table"
3ITEM_KEY='{"id":{"S":"123"}}'
4
5echo "=== Conditional Update with ExpressionAttributeNames ==="
6echo "Using #status instead of 'status' (reserved word)"
7
8# Update with condition using ExpressionAttributeNames
9aws dynamodb update-item \
10  --table-name ${TABLE_NAME} \
11  --key ${ITEM_KEY} \
12  --update-expression "SET #status = :new_status" \
13  --condition-expression "#status = :old_status" \
14  --expression-attribute-names '{"#status":"status"}' \
15  --expression-attribute-values '{
16    ":new_status":{"S":"completed"},
17    ":old_status":{"S":"pending"}
18  }' \
19  --return-values ALL_NEW 2>&1
20
21if [ $? -eq 0 ]; then
22  echo "✓ Conditional update successful"
23else
24  echo "✗ Conditional check failed"
25  echo "Get current item state and adjust condition"
26fi

Retry Conditional Update with Exponential Backoff

1#!/bin/bash
2TABLE_NAME="my-table"
3ITEM_KEY='{"id":{"S":"123"}}'
4MAX_RETRIES=3
5
6echo "=== Conditional Update with Retry Logic ==="
7
8for ATTEMPT in $(seq 1 ${MAX_RETRIES}); do
9  echo "\nAttempt ${ATTEMPT} of ${MAX_RETRIES}"
10  
11  # Get current state first
12  CURRENT_STATUS=$(aws dynamodb get-item \
13    --table-name ${TABLE_NAME} \
14    --key ${ITEM_KEY} \
15    --query 'Item.status.S' \
16    --output text)
17  
18  echo "Current status: ${CURRENT_STATUS}"
19  
20  # Try conditional update
21  aws dynamodb update-item \
22    --table-name ${TABLE_NAME} \
23    --key ${ITEM_KEY} \
24    --update-expression "SET #status = :new_status" \
25    --condition-expression "#status = :old_status" \
26    --expression-attribute-names '{"#status":"status"}' \
27    --expression-attribute-values "{
28      ":new_status":{"S":"completed"},
29      ":old_status":{"S":"${CURRENT_STATUS}"}
30    }" \
31    --return-values ALL_NEW 2>&1
32  
33  if [ $? -eq 0 ]; then
34    echo "✓ Update successful"
35    break
36  else
37    if [ ${ATTEMPT} -lt ${MAX_RETRIES} ]; then
38      DELAY=$((2 ** ATTEMPT))
39      echo "✗ Update failed, retrying in ${DELAY}s..."
40      sleep ${DELAY}
41    else
42      echo "✗ Update failed after ${MAX_RETRIES} attempts"
43    fi
44  fi
45done

Provider Information

This error code is specific to AWS services. For more information, refer to the official AWS documentation.

#Common Causes

✓Solutions

</>Code Examples

↗Related Errors

Provider Information