ConditionalCheckFailedException
AWS ConditionalCheckFailedException means a DynamoDB conditional request failed because the condition expression evaluated to false (HTTP 400).
Last reviewed: February 12, 2026|Editorial standard: source-backed technical guidance
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).
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
Compare Guide
429 Too Many Requests vs 503 Service Unavailable
Use 429 for caller-specific throttling and 503 for service-wide outages, so retry behavior, escalation paths, and incident ownership stay correct.
Compare Guide
AWS ThrottlingException vs GCP RESOURCE_EXHAUSTED
Compare AWS ThrottlingException and GCP RESOURCE_EXHAUSTED to separate rate limiting from quota/resource exhaustion and choose the remediation path.
Playbook
Conflict and Concurrency Playbook (409 / 412 / OptimisticLock)
Use this playbook to separate true write conflicts from stale precondition failures, then apply safe re-fetch, optimistic-lock, and retry choices.
Playbook
Rate Limit Recovery Playbook (429 / ThrottlingException / RESOURCE_EXHAUSTED)
Use this playbook to separate transient throttling from hard quota exhaustion and apply retry, traffic-shaping, and quota-capacity fixes safely.
Official References
Provider Context
This guidance is specific to AWS services. Always validate implementation details against official provider documentation before deploying to production.