DynamoDB ConditionalCheckFailedException

TL;DR — Yazmanız, mevcut öğeye karşı false olarak değerlendirilen bir ConditionExpression taşıdı, bu yüzden DynamoDB yazmayı reddetti ve öğeye dokunmadı. Bu genellikle beklenen bir durumdur (iyimser eşzamanlılık, "yoksa oluştur") — onu yakalayın ve dallanın, körü körüne yeniden denemeyin.

Ne anlama gelir

Bir ValidationException'ın aksine, istek iyi biçimlendirilmişti. DynamoDB koşulunuzu değerlendirdi ve sağlanmadı, bu yüzden PutItem / UpdateItem / DeleteItem (veya bir TransactWriteItems içindeki tek bir öğe) reddedildi. Hiçbir veri değişmedi. HTTP 400 döndürür ve olduğu gibi yeniden denenebilir değildir.

Neden olur

• Bir oluşturmada attribute_not_exists(pk) koruması — öğe zaten var (yinelenen bir ekleme).
• Bir güncelleme/silmede attribute_exists(pk) koruması — öğe gitmiş.
• İyimser eşzamanlılık — başka bir yazıcının önce ulaştığı bir version = :expected (veya updatedAt) kontrolü.
• İş kuralı korumaları — depolanan öğeyle artık eşleşmeyen balance >= :amount, #status = :expected.

Nasıl düzeltilir

1. Bunu bir hata değil, normal bir sonuç olarak ele alın. İstisnayı yakalayın ve başarısız bir koşulun akışınızda ne anlama geldiğine karar verin (öğe zaten var → döndürün; sürüm bayat → yeniden okuyun ve yeni sürümle yeniden deneyin).
2. Mevcut öğeyi geri okuyun. İkinci bir gidiş-dönüş olmadan hataya neden olan öğeyi almak için ReturnValuesOnConditionCheckFailure: 'ALL_OLD' ayarlayın — istisnanın kendisi üzerinde geri gelir (Item alanı) ve hiç okuma kapasitesi tüketilmez.
3. Eşzamanlılık için yeniden okuyun + yeniden hesaplayın, sonra yeni sürümle yeniden deneyin — aynı beklenen değeri tekrar göndermeyin.

Bu yeniden-oku-ve-karşılaştır döngüsü, DynoTable'ın hazırlama alanının elle yapılan düzenlemeler için yaptığının ta kendisidir — yazma işlemlerinizi hazırlama alanına alır ve iyimser kilitleme çakışmasında mevcut öğeyi değişikliğinizin yanında gösterir; böylece hiçbir şey gönderilmeden önce çakışmayı çözebilirsiniz.

Örnek

import {DynamoDBClient} from '@aws-sdk/client-dynamodb';
import {DynamoDBDocumentClient, PutCommand} from '@aws-sdk/lib-dynamodb';
import {ConditionalCheckFailedException} from '@aws-sdk/client-dynamodb';

const doc = DynamoDBDocumentClient.from(new DynamoDBClient({}));

try {
  await doc.send(
    new PutCommand({
      TableName: 'Users',
      Item: {pk: 'USER#1', email: 'a@b.com'},
      ConditionExpression: 'attribute_not_exists(pk)' // create-only
    })
  );
} catch (err) {
  if (err instanceof ConditionalCheckFailedException) {
    // Expected: the user already exists. Handle gracefully.
    return {alreadyExists: true};
  }
  throw err;
}

SSS

DynamoDB'de bir ConditionalCheckFailedException'a ne neden olur? Bir yazma (PutItem, UpdateItem, DeleteItem veya bir TransactWrite öğesi), mevcut öğeye karşı false olarak değerlendirilen bir ConditionExpression taşıdı — örneğin zaten var olan bir anahtarda attribute_not_exists(pk) ya da artık eşleşmeyen bir sürüm kontrolü. DynamoDB yazmayı reddeder ve öğeyi değiştirmeden bırakır.

Bir ConditionalCheckFailedException'ın uygulamamı çökertmesini nasıl durdururum? İstisnayı yakalayın ve onu bir hata değil, beklenen bir sonuç olarak ele alın. Başarısız bir koşul genellikle "başkası önce ulaştı" (iyimser eşzamanlılık) ya da "öğe zaten var" anlamına gelir — körü körüne yeniden denemek yerine bunun üzerine dallanın.

Nasıl yeniden oluşturulur

Zaten var olan bir anahtara karşı attribute_not_exists ile korunan bir PutItem:

await client.send(
  new PutItemCommand({
    TableName: 'orders',
    Item: {pk: {S: 'ORDER#1'}, sk: {S: 'META'}},
    ConditionExpression: 'attribute_not_exists(pk)'
  })
);

Gerçek çıktı:

ConditionalCheckFailedException: The conditional request failed
HTTP 400

Mesaj bilinçli olarak bilgi vermez — koşulun hangi kısmının başarısız olduğunu ya da öğenin gerçekte ne tuttuğunu asla söylemez. ReturnValuesOnConditionCheckFailure: "ALL_OLD" geçirin; mevcut öğe error.Item üzerinde geri gelir ve bu, işi bir tahminden bir farka dönüştürür.

İlgili hatalar

• TransactionCanceledException — bir işlemin içinde başarısız bir koşul.
• ValidationException (genel bakış)
• Kod örneği: Conditional write in Node.js · Python (boto3) ile — çalıştırılabilir ConditionExpression desenleri.
• Öğrenin: Condition expressions · Atomic counters

Kaynaklar

• Error handling with DynamoDB — Amazon DynamoDB Developer Guide
• PutItem — Amazon DynamoDB API Reference
• DynamoDB condition expression examples — Amazon DynamoDB Developer Guide

En son 2026-07-13 tarihinde yukarıda bağlantısı verilen resmi AWS belgelerine karşı doğrulandı.

2026-07-26 tarihinde AWS SDK for JavaScript v3.1095.0 ile DynamoDB Local 2.x'e karşı yeniden üretildi — yukarıdaki çıktı birebir alınmıştır.