ConditionalCheckFailedException
AWS ConditionalCheckFailedException means a DynamoDB conditional request failed because the condition expression evaluated to false (HTTP 400).
Last reviewed: February 12, 2026|Source-backed guidance under our editorial policy
Start Here
Use the closest compare guide, playbook, or adjacent error page to narrow the decision faster before you start changing production systems.
This page is part of the Error Reference library. Learn more about the project or report a correction.
What Does Conditional Check Failed Exception Mean?
DynamoDB evaluated your condition and rejected the write as false, so this is a business-state/concurrency conflict, not a capacity throttling event.
Common Causes
- -ConditionExpression evaluates to false against current item attributes.
- -Optimistic-lock version attribute changed since client read snapshot.
- -Expected attribute existence/non-existence assumption is no longer true.
- -Concurrent updates reorder business invariants between read and write stages.
How to Fix Conditional Check Failed Exception
- 1Read current item state and evaluate why the condition predicate fails.
- 2Update condition expression to match intended invariant exactly.
- 3For optimistic locking, refresh version value and retry with conflict-aware logic.
- 4Avoid blind retries; re-evaluate business conditions before write attempts.
Step-by-Step Diagnosis for Conditional Check Failed Exception
- 1Log condition expression, expression attribute values, and item snapshot at failure time.
- 2Inspect write ordering and competing writers for the same partition/sort key.
- 3Replay condition evaluation in a controlled test using captured item state.
- 4Verify transaction semantics when conditional updates are chained with other operations.
Condition Expression Semantics Review
- -Replay the exact ConditionExpression against captured item state (example:
attribute_not_exists(pk)fails because item already exists). - -Audit expression attribute names/values mapping for runtime substitutions (example: placeholder
:expectedStatusresolves to stale value).
Concurrency and State-Transition Trace
- -Trace competing writers on the same key across services (example: worker B updates version before worker A commits optimistic-lock write).
- -Inspect workflow ordering around state transitions (example: async compensator moves item to COMPLETED before pending-state update arrives).
Seen in Production
Optimistic locking update uses stale version number
Frequency: common
Example: Two services update the same item; second write fails because version condition no longer matches.
Fix: Refetch item, merge changes, and retry with updated version token.
Business rule condition becomes invalid after async side effect
Frequency: rare
Example: A delayed worker expects status PENDING, but another workflow already transitions item to COMPLETED.
Fix: Re-evaluate workflow ordering and condition predicates for eventual consistency windows.
Debugging Tools
- -Item state snapshot logging
- -Condition expression replay tests
- -Concurrency/write-order telemetry
- -DynamoDB Streams event inspection
How to Verify the Fix
- -Re-run conditional write and confirm it succeeds for valid item state.
- -Ensure invalid business states still fail as intended by updated conditions.
- -Monitor conditional failure rates for expected baseline in concurrent workloads.
How to Prevent Recurrence
- -Design explicit state-transition rules and encode them in ConditionExpressions.
- -Use optimistic concurrency tokens/version fields consistently across writers.
- -Track conditional failure metrics by operation to detect logic regressions.
Pro Tip
- -store previous-state snapshots with write intents in logs so failed conditions can be diagnosed as deterministic state mismatches rather than retried blindly.
Decision Support
Official References
Provider Context
This guidance is specific to AWS services. Always validate implementation details against official provider documentation before deploying to production.