ConditionalCheckFailedException ☁️ AWS

ConditionalCheckFailedException: The conditional request failed

A write’s ConditionExpression evaluated to false, so DynamoDB didn’t perform it — often exactly as designed.

Seen on: AWS

Meaning

Conditions like attribute_not_exists(pk) (create-only) or version = :v (optimistic locking) fail when the item already exists or changed. Handle it as a business outcome (duplicate, conflict), not a crash.

Common causes

  • Item already exists (attribute_not_exists)
  • Version/attribute changed by another writer
  • Condition expression references the wrong attribute name

⚡ Quick fix

  1. Catch the exception and handle duplicate/conflict
  2. Re-read and retry with the new version
  3. Use ReturnValuesOnConditionCheckFailure to see the current item

Detailed fix by platform

Python

  1. python
    try:
    table.put_item(Item=item, ConditionExpression="attribute_not_exists(pk)")
except table.meta.client.exceptions.ConditionalCheckFailedException:
    pass  # already exists

How to diagnose

  1. Condition — Expression and values
  2. Item — Current item state

🔧 Still not fixed?

Many errors look alike. If the steps above didn’t solve it, one of these is probably what you’re facing:

🧠 Still stuck? Analyze your error

Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.