ConditionalCheckFailedException: The conditional request failed

What it means

A conditional write asks DynamoDB to apply a change only if a statement about the current item is true, and to evaluate that statement atomically with the write itself. When the statement is false, DynamoDB does not write and raises ConditionalCheckFailedException.

Nothing has gone wrong. This is the feature working. The exception is how a conditional write reports "the condition you gave me was not satisfied", and it is the entire point of asking for the condition in the first place. The atomicity is what makes it valuable: no separate read can tell you whether an item exists and then safely act on that answer, because another writer can act in between. The condition and the write happen together or not at all.

Where it becomes a real problem is when code treats it as an infrastructure failure. An idempotent insert guarded by attribute_not_exists(pk) will fail this way every single time a message is redelivered — and SQS, EventBridge and Lambda's own async retries all deliver at least once, so duplicates are normal rather than exceptional. If that exception propagates out of the handler, the invocation fails, the event is retried, the retry fails identically, and eventually a message that was processed correctly the first time lands in a dead-letter queue.

That is why the frequency matters more than the occurrence. A low, steady rate under concurrency is optimistic locking working: writers contending, one winning, the loser re-reading and trying again. A sudden jump, or a rate close to every attempt, means the condition has stopped describing reality — an attribute renamed, a type changed, a key format migrated — and every write is now being rejected for a reason that has nothing to do with contention. Seeing which invocations carried a retry, and what the item looked like when the check failed, is what separates the two.

What it looks like in CloudWatch

This is the shape the failure arrives in: the lines of one invocation scattered among everything else the log group received at the same moment.

The panel on the right is generated by running the excerpt on the left through the same parser that powers the free web stitcher — it is what the tool actually produces for this input, not an illustration of it.

How to confirm it from the logs

Read the condition expression in the code that raised it, then work out which branch it guarded. attribute_not_exists(pk) failing means the item already exists. A version check failing means someone else wrote first. A status check failing means the record was not in the state you required.

The frequency tells you whether this is a problem. A steady low rate under concurrency is the expected shape of optimistic locking — contention happening and being handled. A sudden rise, or a rate near 100%, means the condition no longer matches reality: a schema change, a backfill, or a key format that moved.

Causes, most likely first

Fixes

jsimport { ConditionalCheckFailedException } from "@aws-sdk/client-dynamodb";

try {
  await client.send(new PutItemCommand({
    TableName: "orders",
    Item: item,
    ConditionExpression: "attribute_not_exists(pk)"
  }));
  return { created: true };
} catch (error) {
  if (error instanceof ConditionalCheckFailedException) {
    // Already there — this request is a duplicate, which is fine.
    return { created: false, duplicate: true };
  }
  throw error;
}

jsasync function updateWithRetry(id, mutate, attempts = 5) {
  for (let attempt = 0; attempt < attempts; attempt += 1) {
    const current = await getItem(id);
    try {
      return await putItem(mutate(current), {
        ConditionExpression: "version = :v",
        ExpressionAttributeValues: { ":v": current.version }
      });
    } catch (error) {
      if (error.name !== "ConditionalCheckFailedException") throw error;
      // Someone else wrote; loop re-reads and recomputes.
    }
  }
  throw new Error(`Could not update ${id} after ${attempts} attempts`);
}

jsawait client.send(new PutItemCommand({
  TableName: "orders",
  Item: item,
  ConditionExpression: "attribute_not_exists(pk)",
  ReturnValuesOnConditionCheckFailure: "ALL_OLD"
}));
// On failure, error.Item holds the record that caused the condition to fail.

Also seen as

The same underlying failure, worded differently by a different runtime, SDK version, or logging layer. All of these land here — there is no separate page for each phrasing.

Related errors

Errors that show up alongside this one, or that people mistake for it.

References

• Amazon DynamoDB Developer Guide — Condition expressions
• Amazon DynamoDB Developer Guide — Optimistic locking with version number